✨ [Feature]

[orieasy1]

Basic Application Flow
When you start the Spring Boot application and access http://localhost:8080, the Swagger UI will appear. You can use it to test the APIs by inputting appropriate request values.

The basic flow can be summarized as:

The client-side sends requests to the backend using HTML/CSS buttons or forms.
The backend processes the request, interacts with the database, and sends a response back to the client.
Layered Architecture
Spring Boot follows a layered architecture where each layer communicates with the adjacent layers only.

Presentation Layer: Handles HTTP requests and forwards them to the business logic.

Controller classes handle this layer.
Example: Receiving a request to view a to-do list and forwarding it to the service layer.
Business Layer: Processes the business logic.

Service classes handle this layer.
Example: Processing logic for creating a new challenge or managing exceptions.
Persistence Layer: Handles database interactions.

Repository classes manage database access.
Example: Saving or retrieving challenge or to-do list data.
Error Documentation
Each controller method defines its own set of possible exceptions. These exceptions are documented under the docs package.

Error Documentation Example

@ExceptionDoc
public class AdminClassroomFilterExceptionDocs implements SwaggerExampleExceptions {

    @ExplainError
    public GlobalCodeException TOKEN_EXPIRED = new AuthException(AuthErrorCode.TOKEN_EXPIRED);

    @ExplainError
    public GlobalCodeException TOKEN_NOT_FOUND = new AuthException(AuthErrorCode.TOKEN_NOT_FOUND);

    @ExplainError
    public GlobalCodeException INVALID_TOKEN = new AuthException(AuthErrorCode.INVALID_TOKEN);

    @ExplainError("This error occurs when the building does not exist.")
    public GlobalCodeException BUILDING_NOT_FOUND = new BuildingException(BuildingErrorCode.BUILDING_NOT_FOUND);

    @ExplainError("This error occurs when the floor does not exist.")
    public GlobalCodeException FLOOR_NOT_FOUND = new BuildingException(BuildingErrorCode.FLOOR_NOT_FOUND);

    @ExplainError("This error occurs when the reservation date is in the past.")
    public GlobalCodeException PAST_DATE_RESERVATION = new ReservationException(ReservationErrorCode.PAST_DATE_RESERVATION);

    @ExplainError("This error occurs when the reservation date is beyond one month.")
    public GlobalCodeException FUTURE_DATE_LIMIT_EXCEEDED = new ReservationException(ReservationErrorCode.FUTURE_DATE_LIMIT_EXCEEDED);
}

Controller Annotation
In the Controller, use the @ApiErrorExceptionsExample annotation to link the error documentation:

@ApiErrorExceptionsExample(AdminClassroomFilterExceptionDocs.class)

Example Controller

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/v1/admin/classrooms")
@Tag(name = "Admin Classroom Controller", description = "[Admin] Classroom Management API")
public class AdminClassroomController {

    private final AdminClassroomService adminClassroomService;

    @PostMapping
    @Operation(summary = "Filter classroom status")
    @ApiErrorExceptionsExample(AdminClassroomFilterExceptionDocs.class)
    public ResponseEntity<AdminClassroomStatusResponse> getClassrooms(
            @RequestBody AdminClassroomStatusRequest request) {

        AdminClassroomStatusResponse response = adminClassroomService.findClassroomsByFilter(request);
        return ResponseEntity.ok(response);
    }

    @GetMapping("/info/{id}")
    @Operation(summary = "Retrieve classroom details")
    @ApiErrorExceptionsExample(AdminClassroomSearchExceptionDocs.class)
    public ResponseEntity<AdminClassroomDetailResponse> findByClassroomIdAndDate(
            @Parameter(description = "Classroom ID", example = "1")
            @PathVariable("id") Long id,
            @Parameter(description = "Date", example = "2024-11-03")
            @RequestParam("date") LocalDate date) {

        AdminClassroomDetailResponse classroom = adminClassroomService.findClassroomByIdAndDate(id, date);
        return ResponseEntity.ok(classroom);
    }
}