andwati/cymelle
1
0
Fork 0
mirror of https://github.com/andwati/cymelle.git synced 2026-10-26 03:42:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

setup operation descriptions for swagger.

Browse Source
This commit is contained in:
andwati
2026-06-12 18:36:55 +03:00
parent 885be904ad
commit 4a5357ee5f
4 changed files with 93 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
orders-backend/src/main/java/com/andwati/orders/controller/FareController.java
+16 -2
View File
@@ -2,6 +2,8 @@ package com.andwati.orders.controller;
import com.andwati.orders.dto.response.FareCalculationResponse;
import com.andwati.orders.services.FareCalculationService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.constraints.DecimalMin;
import jakarta.validation.constraints.NotNull;
@@ -13,7 +15,6 @@ import org.springframework.web.bind.annotation.RestController;
import java.math.BigDecimal;
@Tag(name = "Fare", description = "Calculate trip fares")
@Validated
@RestController
public class FareController {
@@ -24,17 +25,30 @@ public class FareController {
this.fareCalculationService = fareCalculationService;
}
@Operation(
summary = "Calculate a trip fare",
description = """
Calculates the final fare for a trip distance using the configured base fare, per-kilometer rate,
optional surge multiplier, and minimum fare. If no surge multiplier is provided, the default
configured multiplier is used.
"""
)
@GetMapping("/api/fare/calculate")
public FareCalculationResponse calculateFare(
@Parameter(description = "Trip distance in kilometers. Must be greater than 0.", example = "12.5")
@RequestParam
@NotNull(message = "distanceKm is required")
@DecimalMin(value = "0.0", inclusive = false, message = "distanceKm must be greater than 0")
BigDecimal distanceKm,
@Parameter(
description = "Optional surge multiplier. Must be greater than or equal to 1.0.",
example = "1.25"
)
@RequestParam(required = false)
@DecimalMin(value = "1.0", message = "surgeMultiplier must be greater than or equal to 1.0")
BigDecimal surgeMultiplier
) {
return fareCalculationService.calculateFare(distanceKm, surgeMultiplier);
}
}
}
orders-backend/src/main/java/com/andwati/orders/controller/HealthController.java
+9 -2
View File
@@ -1,5 +1,6 @@
package com.andwati.orders.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@@ -7,12 +8,18 @@ import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@Tag(name = "Health", description = "Health check endpoint")
@RestController
public class HealthController {
@Operation(
summary = "Check API health",
description = """
Returns a lightweight status response that can be used by clients, monitors, or load balancers
to verify that the API is running.
"""
)
@GetMapping("/api/health")
public Map<String, String> health() {
return Map.of("status", "UP");
}
}
}
orders-backend/src/main/java/com/andwati/orders/controller/InventoryController.java
+18 -3
View File
@@ -3,15 +3,15 @@ package com.andwati.orders.controller;
import com.andwati.orders.dto.response.InventoryResponse;
import com.andwati.orders.dto.response.LowStockInventoryResponse;
import com.andwati.orders.services.InventoryService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@Tag(name = "Inventory", description = "View inventory and low-stock items")
@RestController
@RequestMapping("/api/inventory")
public class InventoryController {
@@ -22,15 +22,30 @@ public class InventoryController {
this.inventoryService = inventoryService;
}
@Operation(
summary = "List inventory",
description = "Returns the current inventory for all products, including quantities and stock status."
)
@GetMapping
public InventoryResponse getInventory() {
return inventoryService.getInventory();
}
@Operation(
summary = "List low-stock inventory",
description = """
Returns inventory items whose available quantity is at or below the requested threshold.
When the threshold is omitted, the API uses the configured low-stock threshold.
"""
)
@GetMapping("/low-stock")
public LowStockInventoryResponse getLowStockItems(
@Parameter(
description = "Optional low-stock threshold. Must be greater than or equal to 0.",
example = "10"
)
@RequestParam(required = false) Integer threshold
) {
return inventoryService.getLowStockItems(threshold);
}
}
}
orders-backend/src/main/java/com/andwati/orders/controller/OrderController.java
+50 -3
View File
@@ -7,6 +7,8 @@ import com.andwati.orders.dto.response.OrderSummaryResponse;
import com.andwati.orders.dto.response.PageResponse;
import com.andwati.orders.model.OrderStatus;
import com.andwati.orders.services.OrderService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.format.annotation.DateTimeFormat;
@@ -27,37 +29,82 @@ public class OrderController {
this.orderService = orderService;
}
@Operation(
summary = "Place an order",
description = """
Creates a new order for one or more products. The API validates that products exist, are active,
and have enough available stock, then deducts the ordered quantities from inventory.
"""
)
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public OrderResponse placeOrder(@Valid @RequestBody CreateOrderRequest request) {
return orderService.placeOrder(request);
}
@Operation(
summary = "List orders",
description = """
Returns a paginated list of order summaries sorted by newest first. Results can be filtered by
order status and by an inclusive created-date range.
"""
)
@GetMapping
public PageResponse<OrderSummaryResponse> listOrders(
@Parameter(description = "Optional order status filter.", example = "PLACED")
@RequestParam(required = false) OrderStatus status,
@Parameter(
description = "Optional start date for the created-date filter, inclusive.",
example = "2026-06-01"
)
@RequestParam(required = false)
@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
LocalDate from,
@Parameter(
description = "Optional end date for the created-date filter, inclusive.",
example = "2026-06-30"
)
@RequestParam(required = false)
@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
LocalDate to,
@Parameter(description = "Zero-based page index.", example = "0")
@RequestParam(defaultValue = "0") int page,
@Parameter(
description = "Page size. Values are normalized to the supported range of 1 to 100.",
example = "20"
)
@RequestParam(defaultValue = "20") int size
) {
return orderService.listOrders(status, from, to, page, size);
}
@Operation(
summary = "Get an order",
description = "Returns a single order by ID, including its line items, totals, status, and timestamps."
)
@GetMapping("/{id}")
public OrderResponse getOrder(@PathVariable UUID id) {
public OrderResponse getOrder(
@Parameter(description = "Order ID.", example = "11111111-1111-1111-1111-111111111111")
@PathVariable UUID id
) {
return orderService.getOrder(id);
}
@Operation(
summary = "Cancel an order",
description = """
Cancels an existing order when it is still cancellable and restores the ordered quantities back
into inventory. Orders that are already cancelled or otherwise not cancellable are rejected.
"""
)
@DeleteMapping("/{id}")
public CancelOrderResponse cancelOrder(@PathVariable UUID id) {
public CancelOrderResponse cancelOrder(
@Parameter(description = "Order ID.", example = "11111111-1111-1111-1111-111111111111")
@PathVariable UUID id
) {
return orderService.cancelOrder(id);
}
}
}