feat: impl swagger notes

src/main/java/com/fiap/tc/adapter/web/CategoryController.java

@@ -23,7 +23,7 @@
 
 @RestController
 @RequestMapping(path = URLMapping.ROOT_API_CATEGORIES)
-@Api(tags = "Categories API V1", produces = APPLICATION_JSON_VALUE)
+@Api(tags = "Categories API V1", produces = APPLICATION_JSON_VALUE, consumes = APPLICATION_JSON_VALUE)
 public class CategoryController {
 
     private final RegisterCategoryInputPort registerCategoryInputPort;
@@ -40,52 +40,56 @@ public CategoryController(RegisterCategoryInputPort registerCategoryInputPort,
         this.listCategoriesInputPort = listCategoriesInputPort;
     }
 
-    @ApiOperation(value = "List Categories")
+    @ApiOperation(value = "list of categories", notes = "(Private Endpoint) This endpoint is responsible for listing the categories registered in the snack bar's system. It is used on the administrative screen to assist in product creation.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "List Categories", response = CategoryEntity.class)
+            @ApiResponse(code = 200, message = "Successfully retrieved list", response = Category.class, responseContainer = "Page"),
+            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @GetMapping
     @PreAuthorize("hasAuthority('LIST_CATEGORIES')")
     public ResponseEntity<Page<Category>> list(
-            @ApiParam(required = true, value = "Authorization: Bearer <TOKEN>") @RequestHeader(value = "Authorization") String authorization,
-            @ApiParam(required = true, value = "Categories Pagination") Pageable pageable) {
+            @ApiParam(required = true, value = "Pagination information") Pageable pageable) {
         return ok(listCategoriesInputPort.list(pageable));
     }
 
-    @ApiOperation(value = "Save/Update Category")
+    @ApiOperation(value = "create/update category", notes = "(Private Endpoint) This endpoint is responsible for creating or modifying a category. It is used on the administrative screen for managing categories and products.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Save Category", response = CategoryEntity.class)
+            @ApiResponse(code = 200, message = "Successfully saved/updated category", response = CategoryEntity.class),
+            @ApiResponse(code = 401, message = "You are not authorized to perform this action"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @PutMapping(produces = APPLICATION_JSON_VALUE, consumes = APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAuthority('REGISTER_CATEGORIES')")
     public ResponseEntity<Category> saveOrUpdate(
-            @ApiParam(required = true, value = "Authorization: Bearer <TOKEN>") @RequestHeader(value = "Authorization") String authorization,
-            @RequestBody @Valid CategoryRequest category) {
+            @ApiParam(value = "Category details for saving/updating", required = true) @RequestBody @Valid CategoryRequest category) {
         return ok(registerCategoryInputPort.register(category));
     }
 
-    @ApiOperation(value = "Find Category")
+    @ApiOperation(value = "get category by id", notes = "(Private Endpoint) This endpoint is responsible for fetching a category through its unique identifier. It is used on the administrative screen to assist in product creation.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Find Category", response = CategoryEntity.class)
+            @ApiResponse(code = 200, message = "Successfully retrieved category", response = CategoryEntity.class),
+            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @GetMapping(path = "/{id}")
     @PreAuthorize("hasAuthority('SEARCH_CATEGORIES')")
     public ResponseEntity<Category> get(
-            @ApiParam(required = true, value = "Authorization: Bearer <TOKEN>") @RequestHeader(value = "Authorization") String authorization,
-            @PathVariable UUID id) {
+            @ApiParam(value = "ID of the category to be retrieved", required = true) @PathVariable UUID id) {
         return ok(loadCategoryInputPort.load(id));
     }
 
-    @ApiOperation(value = "Delete Category")
+    @ApiOperation(value = "delete category by id", notes = "(Private Endpoint) This endpoint is responsible for removing a category through its unique identifier. It is used on the administrative screen for managing categories and products.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Delete Category", response = CategoryEntity.class)
+            @ApiResponse(code = 200, message = "Successfully deleted category", response = CategoryEntity.class),
+            @ApiResponse(code = 401, message = "You are not authorized to perform this action"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @DeleteMapping(path = "/{id}")
     @PreAuthorize("hasAuthority('DELETE_CATEGORIES')")
     public ResponseEntity<DefaultResponse> delete(
-            @ApiParam(required = true, value = "Authorization: Bearer <TOKEN>") @RequestHeader(value = "Authorization") String authorization,
-            @PathVariable UUID id) {
+            @ApiParam(value = "ID of the category to be deleted", required = true) @PathVariable UUID id) {
         deleteCategoryInputPort.delete(id);
         return ok(new DefaultResponse());
     }
-}
+}

src/main/java/com/fiap/tc/adapter/web/CustomerController.java

@@ -41,48 +41,49 @@ public CustomerController(
         this.deleteCustomerInputPort = deleteCustomerInputPort;
     }
 
-
-    @ApiOperation(value = "List Customers")
+    @ApiOperation(value = "list of customers", notes = "(Private Endpoint) This endpoint queries the entire customer database for potential promotional campaigns.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "List Categories", response = CustomerEntity.class)
+            @ApiResponse(code = 200, message = "Successfully retrieved list", response = Customer.class, responseContainer = "Page"),
+            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @GetMapping(path = URLMapping.ROOT_PRIVATE_API_CUSTOMERS)
     @PreAuthorize("hasAuthority('LIST_CUSTOMERS')")
     public ResponseEntity<Page<Customer>> list(
-            @ApiParam(required = true, value = "Categories Pagination") Pageable pageable) {
+            @ApiParam(required = true, value = "Pagination information") Pageable pageable) {
         return ok(listCustomersInputPort.list(pageable));
     }
 
-    @ApiOperation(value = "Save/Update Customer")
+    @ApiOperation(value = "create/update customer", notes = "(Public Endpoint) Customers are presented with a selection interface where they can choose to register using their name, email, and CPF. This endpoint is responsible for completing that registration.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Save Category", response = CustomerEntity.class)
+            @ApiResponse(code = 200, message = "Successfully saved/updated customer", response = Customer.class),
     })
     @PutMapping(produces = APPLICATION_JSON_VALUE, consumes = APPLICATION_JSON_VALUE, path = URLMapping.ROOT_PUBLIC_API_CUSTOMERS)
     public ResponseEntity<Customer> save(
-            @RequestBody @Valid CustomerRequest customer) {
-
+            @ApiParam(value = "Customer details for saving/updating", required = true) @RequestBody @Valid CustomerRequest customer) {
         return ok(registerCustomerInputPort.register(customer));
     }
 
-    @ApiOperation(value = "Find Customer by Document")
+    @ApiOperation(value = "get customer by cpf", notes = "(Public Endpoint) Customers are presented with a selection interface where they can choose to register using their name, email, and CPF. This endpoint is responsible for completing the registration.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Find Customer by Document", response = CustomerEntity.class)
+            @ApiResponse(code = 200, message = "Successfully retrieved customer", response = Customer.class),
     })
     @GetMapping(path = URLMapping.ROOT_PUBLIC_API_CUSTOMERS + "/{document}")
     public ResponseEntity<Customer> get(
-            @PathVariable String document) {
-
+            @ApiParam(value = "Document of the customer to be retrieved", required = true) @PathVariable String document) {
         return ok(loadCustomerInputPort.load(document));
     }
 
-    @ApiOperation(value = "Delete Customer")
+    @ApiOperation(value = "delete customer by cpf", notes = "(Private Endpoint) This endpoint is responsible for removing a customer by their CPF.")
     @ApiResponses(value = {
-            @ApiResponse(code = 204, message = "Delete Customer by Document", response = CustomerEntity.class)
+            @ApiResponse(code = 204, message = "Successfully deleted customer"),
+            @ApiResponse(code = 401, message = "You are not authorized to perform this action"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @DeleteMapping(path = URLMapping.ROOT_PRIVATE_API_CUSTOMERS + "/{document}")
     @PreAuthorize("hasAuthority('DELETE_CUSTOMERS')")
     public ResponseEntity<Void> delete(
-            @PathVariable String document) {
+            @ApiParam(value = "Document of the customer to be deleted", required = true) @PathVariable String document) {
         deleteCustomerInputPort.delete(document);
         return noContent().build();
     }

src/main/java/com/fiap/tc/adapter/web/HealthCheckController.java

@@ -14,18 +14,16 @@
 
 @RestController
 @RequestMapping(path = URLMapping.ROOT_API_HEALTH)
-@Api(tags = "HealthCheck", produces = APPLICATION_JSON_VALUE)
+@Api(tags = "HealthCheck API V1", produces = APPLICATION_JSON_VALUE)
 public class HealthCheckController {
 
-
-    @ApiOperation(value = "HealthCheck")
+    @ApiOperation(value = "Perform a health check", notes = "(Public Administrative Endpoint) This endpoint is responsible for validating the application's health.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Ready", response = String.class)
+            @ApiResponse(code = 200, message = "Application is healthy", response = String.class)
     })
     @GetMapping
     public ResponseEntity<String> ping() {
         return ok("Ready");
     }
 }
 
-

src/main/java/com/fiap/tc/adapter/web/OrderController.java

@@ -1,6 +1,5 @@
 package com.fiap.tc.adapter.web;
 
-import com.fiap.tc.adapter.repository.entity.CategoryEntity;
 import com.fiap.tc.core.domain.model.Order;
 import com.fiap.tc.core.domain.requests.OrderRequest;
 import com.fiap.tc.core.domain.requests.OrderStatusRequest;
@@ -42,50 +41,53 @@ public OrderController(RegisterOrderInputPort registerOrderInputPort,
         this.listOrdersReadyPreparingInputPort = listOrdersReadyPreparingInputPort;
     }
 
-    @ApiOperation(value = "Find Order")
+    @ApiOperation(value = "get order by id", notes = "(Private Endpoint) This endpoint is responsible for fetching the order using its unique identifier.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Find Order", response = OrderResponse.class)
+            @ApiResponse(code = 200, message = "Successfully retrieved order", response = OrderResponse.class),
+            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @GetMapping(path = URLMapping.ROOT_PRIVATE_API_ORDERS + "/{id}")
     @PreAuthorize("hasAuthority('SEARCH_ORDERS')")
     public ResponseEntity<OrderResponse> get(
             @ApiParam(required = true, value = "Authorization: Bearer <TOKEN>") @RequestHeader(value = "Authorization") String authorization,
-            @PathVariable UUID id) {
+            @ApiParam(value = "ID of the order to be retrieved", required = true) @PathVariable UUID id) {
         return ok(loadOrderInputPort.load(id));
     }
 
-    @ApiOperation(value = "Register Customer Orders")
+    @ApiOperation(value = "create order", notes = "(Public Endpoint) This endpoint is responsible for creating the order, receiving the product identifiers and their quantities.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Save Category", response = OrderResponse.class)
+            @ApiResponse(code = 200, message = "Successfully registered order", response = OrderResponse.class),
     })
     @PostMapping(path = URLMapping.ROOT_PUBLIC_API_ORDERS, produces = APPLICATION_JSON_VALUE, consumes = APPLICATION_JSON_VALUE)
     public ResponseEntity<OrderResponse> register(
-            @RequestBody @Valid OrderRequest request) {
+            @ApiParam(value = "Order details for creating a new order", required = true) @RequestBody @Valid OrderRequest request) {
         return ok(registerOrderInputPort.register(request));
     }
 
-    @ApiOperation(value = "Update Order Status")
+    @ApiOperation(value = "update order status", notes = "(Private Endpoint) This endpoint is responsible for updating the order status for tracking by both the kitchen and the customer (reflected on the system monitor).")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Update Order Status", response = Order.class)
+            @ApiResponse(code = 200, message = "Successfully updated order status", response = Order.class),
+            @ApiResponse(code = 401, message = "You are not authorized to perform this action"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @PutMapping(path = URLMapping.ROOT_PRIVATE_API_ORDERS + "/status", produces = APPLICATION_JSON_VALUE, consumes = APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAuthority('UPDATE_STATUS_ORDERS')")
     public ResponseEntity<Order> updateStatus(
-            @RequestBody @Valid OrderStatusRequest request) {
+            @ApiParam(value = "Order status update details", required = true) @RequestBody @Valid OrderStatusRequest request) {
         return ok(updateStatusOrderInputPort.update(request));
     }
 
-    @ApiOperation(value = "List Orders Preparing or Ready")
+    @ApiOperation(value = "list of orders", notes = "(Private Endpoint) This endpoint is responsible for listing all orders.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "List Orders Preparing or Ready", response = CategoryEntity.class)
+            @ApiResponse(code = 200, message = "Successfully retrieved list of orders", response = Order.class, responseContainer = "Page"),
+            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
+            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
     })
     @GetMapping(path = URLMapping.ROOT_PRIVATE_API_ORDERS)
     @PreAuthorize("hasAuthority('LIST_ORDERS')")
     public ResponseEntity<Page<Order>> list(
-            @ApiParam(required = true, value = "Authorization: Bearer <TOKEN>") @RequestHeader(value = "Authorization") String authorization,
             @ApiParam(required = true, value = "Orders Pagination") Pageable pageable) {
         return ok(listOrdersReadyPreparingInputPort.list(pageable));
     }
-
-
 }

src/main/java/com/fiap/tc/adapter/web/PaymentHookController.java

@@ -3,22 +3,17 @@
 import com.fiap.tc.adapter.web.response.DefaultResponse;
 import com.fiap.tc.core.domain.requests.OrderPaymentRequest;
 import com.fiap.tc.core.port.in.payment.RegisterPaymentInputPort;
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiOperation;
-import io.swagger.annotations.ApiResponse;
-import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.*;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import javax.validation.Valid;
 
 import static org.springframework.http.MediaType.APPLICATION_JSON_VALUE;
 import static org.springframework.http.ResponseEntity.ok;
 
-@RestController
 @RequestMapping(path = URLMapping.ROOT_PUBLIC_API_PAYMENT)
 @Api(tags = "Orders Payment Hook API V1", produces = APPLICATION_JSON_VALUE)
 public class PaymentHookController {
@@ -29,16 +24,15 @@ public PaymentHookController(RegisterPaymentInputPort registerPaymentInputPort)
         this.registerPaymentInputPort = registerPaymentInputPort;
     }
 
-    @ApiOperation(value = "Webhook Register Payment")
+    @ApiOperation(value = "Webhook Register Payment", notes = "(Public Endpoint) This endpoint is responsible for receiving the payment parameters in the selection interface and processing the payment.")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Process Payment", response = DefaultResponse.class)
+            @ApiResponse(code = 200, message = "Successfully processed payment", response = DefaultResponse.class),
+            @ApiResponse(code = 400, message = "Invalid request"),
     })
     @PostMapping(produces = APPLICATION_JSON_VALUE, consumes = APPLICATION_JSON_VALUE)
     public ResponseEntity<DefaultResponse> register(
-            @RequestBody @Valid OrderPaymentRequest request) {
+            @ApiParam(value = "Order payment request details", required = true) @RequestBody @Valid OrderPaymentRequest request) {
         registerPaymentInputPort.register(request);
         return ok(new DefaultResponse());
     }
-
-
-}
+}

src/main/java/com/fiap/tc/adapter/web/TokenController.java

@@ -1,6 +1,7 @@
 package com.fiap.tc.adapter.web;
 
 import com.fiap.tc.common.config.property.OriginApiProperty;
+import io.swagger.annotations.*;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -11,15 +12,24 @@
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
+import static org.springframework.http.MediaType.APPLICATION_JSON_VALUE;
+
 @RestController
-@RequestMapping("/tokens")
+@RequestMapping("/oauth/token")
+@Api(tags = "token-endpoint", produces = APPLICATION_JSON_VALUE)
 public class TokenController {
 
     @Autowired
     private OriginApiProperty originApiProperty;
 
+    @ApiOperation(value = "Revoke Refresh Token", notes = "Revoke the refresh token by deleting the corresponding cookie.")
+    @ApiResponses(value = {
+            @ApiResponse(code = 204, message = "Successfully revoked the refresh token")
+    })
     @DeleteMapping("/revoke")
-    public void revoke(HttpServletRequest req, HttpServletResponse resp) {
+    public void revoke(
+            @ApiParam(value = "HTTP request", required = true) HttpServletRequest req,
+            @ApiParam(value = "HTTP response", required = true) HttpServletResponse resp) {
         Cookie cookie = new Cookie("refreshToken", null);
         cookie.setHttpOnly(true);
         cookie.setSecure(originApiProperty.getSecurity().isEnableHttps());
@@ -29,5 +39,4 @@ public void revoke(HttpServletRequest req, HttpServletResponse resp) {
         resp.addCookie(cookie);
         resp.setStatus(HttpStatus.NO_CONTENT.value());
     }
-
 }