From 4a5357ee5ffb163bd61038d8fc83f4f3573fb65f Mon Sep 17 00:00:00 2001 From: andwati Date: Fri, 12 Jun 2026 18:36:55 +0300 Subject: [PATCH] setup operation descriptions for swagger. --- .../orders/controller/FareController.java | 18 ++++++- .../orders/controller/HealthController.java | 11 +++- .../controller/InventoryController.java | 21 ++++++-- .../orders/controller/OrderController.java | 53 +++++++++++++++++-- 4 files changed, 93 insertions(+), 10 deletions(-) diff --git a/orders-backend/src/main/java/com/andwati/orders/controller/FareController.java b/orders-backend/src/main/java/com/andwati/orders/controller/FareController.java index dbc3b9d..89891df 100644 --- a/orders-backend/src/main/java/com/andwati/orders/controller/FareController.java +++ b/orders-backend/src/main/java/com/andwati/orders/controller/FareController.java @@ -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); } -} \ No newline at end of file +} diff --git a/orders-backend/src/main/java/com/andwati/orders/controller/HealthController.java b/orders-backend/src/main/java/com/andwati/orders/controller/HealthController.java index 424f18c..3abc819 100644 --- a/orders-backend/src/main/java/com/andwati/orders/controller/HealthController.java +++ b/orders-backend/src/main/java/com/andwati/orders/controller/HealthController.java @@ -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 health() { return Map.of("status", "UP"); } -} \ No newline at end of file +} diff --git a/orders-backend/src/main/java/com/andwati/orders/controller/InventoryController.java b/orders-backend/src/main/java/com/andwati/orders/controller/InventoryController.java index a1a2699..570e737 100644 --- a/orders-backend/src/main/java/com/andwati/orders/controller/InventoryController.java +++ b/orders-backend/src/main/java/com/andwati/orders/controller/InventoryController.java @@ -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); } -} \ No newline at end of file +} diff --git a/orders-backend/src/main/java/com/andwati/orders/controller/OrderController.java b/orders-backend/src/main/java/com/andwati/orders/controller/OrderController.java index 049a00e..8169a8b 100644 --- a/orders-backend/src/main/java/com/andwati/orders/controller/OrderController.java +++ b/orders-backend/src/main/java/com/andwati/orders/controller/OrderController.java @@ -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 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); } -} \ No newline at end of file +}