From 73b8abe09d1bc40c84d190a781797e00225a3d25 Mon Sep 17 00:00:00 2001 From: "c_jean.silva" Date: Wed, 31 Jul 2024 18:31:34 -0300 Subject: [PATCH] feat: impl swagger notes --- .../tc/adapter/web/CategoryController.java | 40 ++++++++++--------- .../tc/adapter/web/CustomerController.java | 31 +++++++------- .../tc/adapter/web/HealthCheckController.java | 8 ++-- .../fiap/tc/adapter/web/OrderController.java | 32 ++++++++------- .../tc/adapter/web/PaymentHookController.java | 18 +++------ .../fiap/tc/adapter/web/TokenController.java | 15 +++++-- 6 files changed, 76 insertions(+), 68 deletions(-) diff --git a/src/main/java/com/fiap/tc/adapter/web/CategoryController.java b/src/main/java/com/fiap/tc/adapter/web/CategoryController.java index 8108abb5..6f0916e6 100644 --- a/src/main/java/com/fiap/tc/adapter/web/CategoryController.java +++ b/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> list( - @ApiParam(required = true, value = "Authorization: Bearer ") @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 saveOrUpdate( - @ApiParam(required = true, value = "Authorization: Bearer ") @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 get( - @ApiParam(required = true, value = "Authorization: Bearer ") @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 delete( - @ApiParam(required = true, value = "Authorization: Bearer ") @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()); } -} +} \ No newline at end of file diff --git a/src/main/java/com/fiap/tc/adapter/web/CustomerController.java b/src/main/java/com/fiap/tc/adapter/web/CustomerController.java index 731bd21f..874b1ff8 100644 --- a/src/main/java/com/fiap/tc/adapter/web/CustomerController.java +++ b/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> 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 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 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 delete( - @PathVariable String document) { + @ApiParam(value = "Document of the customer to be deleted", required = true) @PathVariable String document) { deleteCustomerInputPort.delete(document); return noContent().build(); } diff --git a/src/main/java/com/fiap/tc/adapter/web/HealthCheckController.java b/src/main/java/com/fiap/tc/adapter/web/HealthCheckController.java index 831fcde6..9c35087a 100644 --- a/src/main/java/com/fiap/tc/adapter/web/HealthCheckController.java +++ b/src/main/java/com/fiap/tc/adapter/web/HealthCheckController.java @@ -14,13 +14,12 @@ @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 ping() { @@ -28,4 +27,3 @@ public ResponseEntity ping() { } } - diff --git a/src/main/java/com/fiap/tc/adapter/web/OrderController.java b/src/main/java/com/fiap/tc/adapter/web/OrderController.java index 93390678..ed6e751e 100644 --- a/src/main/java/com/fiap/tc/adapter/web/OrderController.java +++ b/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 get( @ApiParam(required = true, value = "Authorization: Bearer ") @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 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 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> list( - @ApiParam(required = true, value = "Authorization: Bearer ") @RequestHeader(value = "Authorization") String authorization, @ApiParam(required = true, value = "Orders Pagination") Pageable pageable) { return ok(listOrdersReadyPreparingInputPort.list(pageable)); } - - } diff --git a/src/main/java/com/fiap/tc/adapter/web/PaymentHookController.java b/src/main/java/com/fiap/tc/adapter/web/PaymentHookController.java index 56d84070..af37b87f 100644 --- a/src/main/java/com/fiap/tc/adapter/web/PaymentHookController.java +++ b/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 register( - @RequestBody @Valid OrderPaymentRequest request) { + @ApiParam(value = "Order payment request details", required = true) @RequestBody @Valid OrderPaymentRequest request) { registerPaymentInputPort.register(request); return ok(new DefaultResponse()); } - - -} +} \ No newline at end of file diff --git a/src/main/java/com/fiap/tc/adapter/web/TokenController.java b/src/main/java/com/fiap/tc/adapter/web/TokenController.java index 343780b9..e020ab3b 100644 --- a/src/main/java/com/fiap/tc/adapter/web/TokenController.java +++ b/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()); } - }