docs: update API documentation

ifspcbt-devspace · Oct 19, 2024 · 3560839 · 3560839
1 parent 60cea83
commit 3560839
Show file tree

Hide file tree

Showing 10 changed files with 371 additions and 190 deletions.
diff --git a/infrastructure/src/main/java/br/com/ifsp/tickets/infra/api/AuthAPI.java b/infrastructure/src/main/java/br/com/ifsp/tickets/infra/api/AuthAPI.java
@@ -6,8 +6,12 @@
 import br.com.ifsp.tickets.infra.contexts.user.models.register.RegisterRequest;
 import br.com.ifsp.tickets.infra.contexts.user.models.update.UpdateUserRequest;
 import br.com.ifsp.tickets.infra.contexts.user.models.user.UserResponse;
+import br.com.ifsp.tickets.infra.shared.APIErrorResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
-import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.http.MediaType;
@@ -19,53 +23,89 @@
 public interface AuthAPI {
 
     @PostMapping(value = "/login", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "User logged in successfully"),
-            @ApiResponse(responseCode = "401", description = "Invalid credentials")
-    })
+    @Operation(
+            summary = "Login",
+            description = "Authenticate user",
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "User logged in successfully", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = LoginResponse.class))),
+                    @ApiResponse(responseCode = "401", description = "Invalid credentials", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<LoginResponse> login(@RequestBody LoginRequest request);
 
     @PostMapping(value = "/register", consumes = MediaType.APPLICATION_JSON_VALUE)
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "201", description = "User registered successfully"),
-            @ApiResponse(responseCode = "400", description = "Invalid request")
-    })
+    @Operation(
+            summary = "Register user",
+            description = "Register a new user",
+            responses = {
+                    @ApiResponse(responseCode = "201", description = "User registered successfully"),
+                    @ApiResponse(responseCode = "400", description = "Invalid request", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Void> register(@RequestBody RegisterRequest request);
 
     @GetMapping(value = "/{id}")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "User found successfully"),
-            @ApiResponse(responseCode = "404", description = "User not found")
-    })
+    @Operation(
+            summary = "Get user by id",
+            description = "Get user information by id",
+            security = {
+                    @SecurityRequirement(name = "bearer")
+            },
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "User found successfully", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = UserResponse.class))),
+                    @ApiResponse(responseCode = "401", description = "Invalid credentials", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "403", description = "Access denied", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "404", description = "User not found", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<UserResponse> getUserById(@PathVariable String id);
 
     @PutMapping(value = "/{id}")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "User updated successfully"),
-            @ApiResponse(responseCode = "401", description = "Invalid credentials"),
-            @ApiResponse(responseCode = "403", description = "Access denied"),
-            @ApiResponse(responseCode = "404", description = "User not found")
-    })
+    @Operation(
+            summary = "Update user",
+            description = "Update user information",
+            security = {
+                    @SecurityRequirement(name = "bearer")
+            },
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "User updated successfully", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = UserResponse.class))),
+                    @ApiResponse(responseCode = "401", description = "Invalid credentials", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "403", description = "Access denied", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "404", description = "User not found", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<UserResponse> updateUser(@PathVariable String id, @RequestBody UpdateUserRequest request);
 
     @PostMapping(value = "/activate/{token}")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "User activated successfully"),
-            @ApiResponse(responseCode = "400", description = "Invalid token")
-    })
+    @Operation(
+            summary = "Activate user",
+            description = "Activate user account",
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "User activated successfully"),
+                    @ApiResponse(responseCode = "400", description = "Invalid token", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Void> activate(@PathVariable String token);
 
     @PostMapping(value = "/recovery/{login}")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "Recovery request sent successfully"),
-            @ApiResponse(responseCode = "400", description = "Invalid login")
-    })
+    @Operation(
+            summary = "Forgot password",
+            description = "Send recovery request to user",
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "Recovery request sent successfully"),
+                    @ApiResponse(responseCode = "400", description = "Invalid login", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Void> forgotPassword(@PathVariable String login, HttpServletRequest request);
 
     @PostMapping(value = "/recovery/change")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "Password changed successfully"),
-            @ApiResponse(responseCode = "400", description = "Invalid request")
-    })
+    @Operation(
+            summary = "Change password",
+            description = "Change user password",
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "Password changed successfully"),
+                    @ApiResponse(responseCode = "400", description = "Invalid request", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Void> accountRecovery(@RequestBody RecoveryRequest request);
 }
diff --git a/infrastructure/src/main/java/br/com/ifsp/tickets/infra/api/CepAPI.java b/infrastructure/src/main/java/br/com/ifsp/tickets/infra/api/CepAPI.java
@@ -1,8 +1,11 @@
 package br.com.ifsp.tickets.infra.api;
 
 import br.com.ifsp.tickets.infra.contexts.zipcode.models.ZipCodeResponse;
+import br.com.ifsp.tickets.infra.shared.APIErrorResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
-import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -14,9 +17,13 @@
 public interface CepAPI {
 
     @GetMapping(value = "/{cep}", produces = "application/json")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Cep found"),
-            @ApiResponse(responseCode = "404", description = "Cep not found")
-    })
+    @Operation(
+            summary = "Get address by cep",
+            description = "Get address information by brazilian zip code",
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "Cep found", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ZipCodeResponse.class))),
+                    @ApiResponse(responseCode = "404", description = "Cep not found", content = @Content(mediaType = "application/json", schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<ZipCodeResponse> get(@PathVariable String cep);
 }
diff --git a/infrastructure/src/main/java/br/com/ifsp/tickets/infra/api/CompanyAPI.java b/infrastructure/src/main/java/br/com/ifsp/tickets/infra/api/CompanyAPI.java
@@ -5,9 +5,13 @@
 import br.com.ifsp.tickets.infra.contexts.company.models.CreateCompanyRequest;
 import br.com.ifsp.tickets.infra.contexts.company.models.SearchCompanyResponse;
 import br.com.ifsp.tickets.infra.contexts.company.models.UpdateCompanyRequest;
+import br.com.ifsp.tickets.infra.shared.APIErrorResponse;
 import br.com.ifsp.tickets.infra.shared.search.AdvancedSearchRequest;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
-import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
@@ -17,42 +21,79 @@
 public interface CompanyAPI {
 
     @PostMapping(consumes = "application/json")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "201", description = "Company created successfully"),
-            @ApiResponse(responseCode = "400", description = "Invalid request")
-    })
+    @Operation(
+            summary = "Create company",
+            description = "Create a new company",
+            security = {
+                    @SecurityRequirement(name = "bearer")
+            },
+            responses = {
+                    @ApiResponse(responseCode = "201", description = "Company created successfully"),
+                    @ApiResponse(responseCode = "400", description = "Invalid request", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "401", description = "Invalid credentials", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "403", description = "Access denied", content = @Content(schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Void> create(@RequestBody CreateCompanyRequest request);
 
     @PutMapping(value = "/{id}", consumes = "application/json", produces = "application/json")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Company updated successfully"),
-            @ApiResponse(responseCode = "404", description = "Company not found"),
-    })
+    @Operation(
+            summary = "Update company",
+            description = "Update company information",
+            security = {
+                    @SecurityRequirement(name = "bearer")
+            },
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "Company updated successfully", content = @Content(schema = @Schema(implementation = CompanyResponse.class))),
+                    @ApiResponse(responseCode = "400", description = "Invalid request", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "401", description = "Invalid credentials", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "403", description = "Access denied", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "404", description = "Company not found", content = @Content(schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<CompanyResponse> update(@PathVariable String id, @RequestBody UpdateCompanyRequest request);
 
     @PostMapping(
             value = "/search",
             produces = "application/json")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Companies list"),
-            @ApiResponse(responseCode = "400", description = "Invalid request")
-    })
+    @Operation(
+            summary = "Search companies",
+            description = "Search companies by name, cnpj, state, city, neighborhood, street, number, complement, zip code, phone, email, website, and contact name",
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "Companies found", content = @Content(schema = @Schema(implementation = Pagination.class))),
+                    @ApiResponse(responseCode = "400", description = "Invalid request", content = @Content(schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Pagination<SearchCompanyResponse>> search(@RequestParam(name = "page", required = false, defaultValue = "0") Integer page,
                                                              @RequestParam(name = "perPage", required = false, defaultValue = "10") Integer perPage,
                                                              @RequestBody AdvancedSearchRequest request);
 
     @GetMapping(value = "/{id}", produces = "application/json")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Company found"),
-            @ApiResponse(responseCode = "404", description = "Company not found")
-    })
+    @Operation(
+            summary = "Get company by id",
+            description = "Get company information by id",
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "Company found", content = @Content(schema = @Schema(implementation = CompanyResponse.class))),
+                    @ApiResponse(responseCode = "404", description = "Company not found", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))
+                    )
+            }
+    )
     ResponseEntity<CompanyResponse> get(@PathVariable String id);
 
     @DeleteMapping(value = "/{id}")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "Company deleted successfully"),
-            @ApiResponse(responseCode = "404", description = "Company not found")
-    })
+    @Operation(
+            summary = "Delete company",
+            description = "Delete company by id",
+            security = {
+                    @SecurityRequirement(name = "bearer")
+            },
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "Company deleted successfully"),
+                    @ApiResponse(responseCode = "401", description = "Invalid credentials", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "403", description = "Access denied", content = @Content(schema = @Schema(implementation = APIErrorResponse.class))),
+                    @ApiResponse(responseCode = "404", description = "Company not found", content = @Content(schema = @Schema(implementation = APIErrorResponse.class)))
+            }
+    )
     ResponseEntity<Void> delete(@PathVariable String id);
 
 }