docs: implement API interfaces with swagger documentation

src/main/java/org/fmazmz/casemanager/exception/GlobalExceptionHandler.java

@@ -9,9 +9,23 @@
 @ControllerAdvice
 public class GlobalExceptionHandler {
 
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ApiErrorResponse> handleGenericException(Exception ex) {
+        return ResponseEntity
+                .status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(new ApiErrorResponse(
+                        HttpStatus.INTERNAL_SERVER_ERROR.name(),
+                        ex.getMessage(),
+                        HttpStatus.INTERNAL_SERVER_ERROR.value()));
+    }
+
     @ExceptionHandler(AccessDeniedException.class)
     public ResponseEntity<ApiErrorResponse> handleAccessDenied(AccessDeniedException ex) {
         return ResponseEntity
                 .status(HttpStatus.FORBIDDEN)
-                .body(new ApiErrorResponse(HttpStatus.FORBIDDEN.name(), ex.getMessage(), HttpStatus.FORBIDDEN.value()));    }
+                .body(new ApiErrorResponse(
+                        HttpStatus.FORBIDDEN.name(),
+                        ex.getMessage(),
+                        HttpStatus.FORBIDDEN.value()));
+    }
 }

src/main/java/org/fmazmz/casemanager/ticket/api/TicketApi.java

@@ -1,34 +1,53 @@
 package org.fmazmz.casemanager.ticket.api;
 
+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.tags.Tag;
 import jakarta.validation.Valid;
 import org.fmazmz.casemanager.ticket.dto.CreateTicketRequest;
 import org.fmazmz.casemanager.ticket.dto.TicketResponse;
-import org.fmazmz.casemanager.ticket.orchestration.TicketOrchestrator;
-import org.fmazmz.casemanager.utils.ApiResponse;
-import org.springframework.http.HttpStatus;
+import org.fmazmz.casemanager.utils.ApiErrorResponse;
+import org.fmazmz.casemanager.utils.ApiResponseWrapper;
+import org.springframework.http.MediaType;
 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;
 
-@RestController
-@RequestMapping("api/v1/tickets")
-public class TicketApi {
-    private final TicketOrchestrator ticketOrchestrator;
-
-    public TicketApi(TicketOrchestrator ticketOrchestrator) {
-        this.ticketOrchestrator = ticketOrchestrator;
-    }
+@Tag(name = "Ticket API", description = "Perform CRUD operations on Tickets")
+@RequestMapping(
+        path = "api/v1/tickets",
+        consumes = MediaType.APPLICATION_JSON_VALUE,
+        produces = MediaType.APPLICATION_JSON_VALUE
+)
+public interface TicketApi {
 
+    @Operation(summary = "Create a new Ticket")
+    @ApiResponse(
+            responseCode = "201",
+            description = "Created",
+            useReturnTypeSchema = true
+    )
+    @ApiResponse(responseCode = "400", description = "Bad Request",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+    )
+    @ApiResponse(responseCode = "401", description = "Unauthorized",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+)
+    @ApiResponse(responseCode = "403", description = "Forbidden",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class)))
+    @ApiResponse(responseCode = "500", description = "Internal Server Error",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class)))
     @PostMapping
-    public ResponseEntity<ApiResponse<TicketResponse>> createTicket(
-            @RequestBody @Valid CreateTicketRequest request) {
-
-        TicketResponse response = ticketOrchestrator.createTicket(request, request.requesterId());
-
-        return ResponseEntity
-                .status(HttpStatus.CREATED)
-                .body(new ApiResponse<>(response));
-    }
+    ResponseEntity<ApiResponseWrapper<TicketResponse>> createTicket(
+            @Valid
+            @RequestBody
+            @io.swagger.v3.oas.annotations.parameters.RequestBody(
+                    required = true,
+                    description = "Payload to create a new Ticket"
+            )
+            CreateTicketRequest request
+            );
 }

src/main/java/org/fmazmz/casemanager/ticket/api/TicketController.java

@@ -0,0 +1,33 @@
+package org.fmazmz.casemanager.ticket.api;
+
+import jakarta.validation.Valid;
+import org.fmazmz.casemanager.ticket.dto.CreateTicketRequest;
+import org.fmazmz.casemanager.ticket.dto.TicketResponse;
+import org.fmazmz.casemanager.ticket.orchestration.TicketOrchestrator;
+import org.fmazmz.casemanager.utils.ApiResponseWrapper;
+import org.springframework.http.HttpStatus;
+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.RestController;
+
+@RestController
+public class TicketController implements TicketApi{
+    private final TicketOrchestrator ticketOrchestrator;
+
+    public TicketController(TicketOrchestrator ticketOrchestrator) {
+        this.ticketOrchestrator = ticketOrchestrator;
+    }
+
+    @PostMapping
+    @Override
+    public ResponseEntity<ApiResponseWrapper<TicketResponse>> createTicket(
+            @RequestBody @Valid CreateTicketRequest request) {
+
+        TicketResponse response = ticketOrchestrator.createTicket(request, request.requesterId());
+
+        return ResponseEntity
+                .status(HttpStatus.CREATED)
+                .body(new ApiResponseWrapper<>(response));
+    }
+}

src/main/java/org/fmazmz/casemanager/user/auth/Oauth2Api.java

@@ -0,0 +1,87 @@
+package org.fmazmz.casemanager.user.auth;
+
+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.media.SchemaProperty;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.fmazmz.casemanager.user.dto.OAuthInfoResponse;
+import org.fmazmz.casemanager.user.dto.SignupRequest;
+import org.fmazmz.casemanager.user.dto.UserResponse;
+import org.fmazmz.casemanager.utils.ApiErrorResponse;
+import org.fmazmz.casemanager.utils.ApiResponseWrapper;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+@Tag(name = "Oauth2 API", description = "Authentication and user onboarding via OAuth2")
+@RequestMapping(
+        path = "api/v1/auth",
+        consumes = MediaType.APPLICATION_JSON_VALUE,
+        produces = MediaType.APPLICATION_JSON_VALUE
+)
+public interface Oauth2Api {
+
+    @Operation(summary = "Get authenticated OAuth2 user info")
+    @ApiResponse(
+            responseCode = "200",
+            description = "OAuth2 user information",
+            content = @Content(
+                    schemaProperties = {
+                            @SchemaProperty(
+                                    name = "data",
+                                    schema = @Schema(oneOf = {OAuthInfoResponse.class, UserResponse.class})
+                            ),
+                            @SchemaProperty(
+                                    name = "requestId",
+                                    schema = @Schema(type = "string", format = "uuid")
+                            ),
+                            @SchemaProperty(
+                                    name = "timestamp",
+                                    schema = @Schema(type = "integer", format = "int64")
+                            )
+                    }
+            )
+    )
+    @ApiResponse(responseCode = "401", description = "Unauthorized",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+    )
+    @ApiResponse(responseCode = "500", description = "Internal Server Error",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+    )
+    @GetMapping("/me")
+    ResponseEntity<ApiResponseWrapper<?>> me(OAuth2AuthenticationToken authentication);
+
+    @Operation(summary = "Complete signup for authenticated OAuth2 user")
+    @ApiResponse(
+            responseCode = "201",
+            description = "Created",
+            useReturnTypeSchema = true
+    )
+    @ApiResponse(responseCode = "400", description = "Bad Request",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+    )
+    @ApiResponse(responseCode = "401", description = "Unauthorized",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+    )
+    @ApiResponse(responseCode = "500", description = "Internal Server Error",
+            content = @Content(schema = @Schema(implementation = ApiErrorResponse.class))
+    )
+    @PostMapping("/signup")
+    ResponseEntity<ApiResponseWrapper<UserResponse>> signup(
+            OAuth2AuthenticationToken authentication,
+            @Valid
+            @RequestBody
+            @io.swagger.v3.oas.annotations.parameters.RequestBody(
+                    required = true,
+                    description = "Payload to complete user signup"
+            )
+            SignupRequest request
+    );
+}

src/main/java/org/fmazmz/casemanager/user/auth/Oauth2Controller.java

@@ -7,7 +7,7 @@
 import org.fmazmz.casemanager.user.dto.UserResponse;
 import org.fmazmz.casemanager.user.model.AuthProvider;
 import org.fmazmz.casemanager.user.model.User;
-import org.fmazmz.casemanager.utils.ApiResponse;
+import org.fmazmz.casemanager.utils.ApiResponseWrapper;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
@@ -17,8 +17,7 @@
 
 @Slf4j
 @RestController
-@RequestMapping("api/v1/auth")
-public class Oauth2Controller {
+public class Oauth2Controller implements Oauth2Api {
 
     private final UserAuth userAuth;
 
@@ -27,7 +26,8 @@ public Oauth2Controller(UserAuth userAuth) {
     }
 
     @GetMapping("/me")
-    public ResponseEntity<ApiResponse<?>> me(OAuth2AuthenticationToken authentication) {
+    @Override
+    public ResponseEntity<ApiResponseWrapper<?>> me(OAuth2AuthenticationToken authentication) {
         var principal = authentication.getPrincipal();
         AuthProvider provider = AuthProvider.fromRegistrationId(
                 authentication.getAuthorizedClientRegistrationId());
@@ -45,21 +45,22 @@ public ResponseEntity<ApiResponse<?>> me(OAuth2AuthenticationToken authenticatio
                     principal.getAttribute(provider.getNameAttribute()),
                     principal.getAttribute(provider.getAvatarAttribute())
             );
-            return ResponseEntity.ok(new ApiResponse<>(response));
+            return ResponseEntity.ok(new ApiResponseWrapper<>(response));
         }
 
-        return ResponseEntity.ok(new ApiResponse<>(UserResponse.from(user.get())));
+        return ResponseEntity.ok(new ApiResponseWrapper<>(UserResponse.from(user.get())));
     }
 
     @PostMapping("/signup")
-    public ResponseEntity<ApiResponse<UserResponse>> signup(
+    @Override
+    public ResponseEntity<ApiResponseWrapper<UserResponse>> signup(
             OAuth2AuthenticationToken authentication,
             @RequestBody @Valid SignupRequest request) {
 
         User user = userAuth.signup(authentication, request);
 
         return ResponseEntity
                 .status(HttpStatus.CREATED)
-                .body(new ApiResponse<>(UserResponse.from(user)));
+                .body(new ApiResponseWrapper<>(UserResponse.from(user)));
     }
 }

src/main/java/org/fmazmz/casemanager/utils/ApiResponse.java → src/main/java/org/fmazmz/casemanager/utils/ApiResponseWrapper.java

@@ -3,13 +3,13 @@
 import java.time.Instant;
 import java.util.UUID;
 
-public record ApiResponse<T>(
+public record ApiResponseWrapper<T>(
         T data,
         UUID requestId,
         Long timestamp
 )
 {
-    public ApiResponse(T data) {
+    public ApiResponseWrapper(T data) {
         this(data, UUID.randomUUID(), Instant.now().toEpochMilli());
     }
 }