[BE-Feat] swagger 관련 어노테이션 추가 #94
Conversation
WalkthroughThe pull request updates the springdoc dependency version and enhances API documentation by adding Swagger annotations to multiple controllers. It refines error handling by updating methods and exception types to use a custom ApiException, and it modifies the structure of error responses to include HTTP status codes. In addition, token field names are renamed to camelCase across the user entity and related tests. A new error code for invalid date/time ranges is introduced, and the date/time validation logic is updated accordingly. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Controller
participant Validator
participant GlobalExceptionHandler
participant ErrorResponse
Client->>Controller: API Request
Controller->>Validator: validateDateTimeRange(...)
Validator-->>Controller: Throw ApiException
Controller->>GlobalExceptionHandler: Pass exception
GlobalExceptionHandler->>ErrorResponse: Create error response with HTTP status
GlobalExceptionHandler-->>Client: Return error response
Possibly related PRs
Suggested reviewers
Poem
Tip 🌐 Web search-backed reviews and chat
✨ Finishing Touches
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
backend/src/main/java/endolphin/backend/domain/user/entity/User.java (1)
13-13: Remove unused import.The
lombok.Setterimport is not used in this class.-import lombok.Setter;backend/src/main/java/endolphin/backend/domain/user/UserService.java (1)
54-56: Consider adding error logging.The error handling improvement using
ApiExceptionwith a specific error code is good. Consider adding debug logging before throwing the exception to aid in troubleshooting.return userRepository.findById(userInfo.userId()) - .orElseThrow(() -> new ApiException(ErrorCode.USER_NOT_FOUND)); + .orElseThrow(() -> { + log.debug("User not found for ID: {}", userInfo.userId()); + return new ApiException(ErrorCode.USER_NOT_FOUND); + });backend/src/main/java/endolphin/backend/global/error/ErrorResponse.java (1)
16-18: Consider adding Swagger documentation for the static factory method.While the record fields are well-documented, the static factory method could benefit from Swagger annotations to document its purpose and usage.
+ @Schema(description = "ErrorCode로부터 ErrorResponse를 생성") public static ErrorResponse of(ErrorCode errorCode) { return new ErrorResponse(errorCode.getHttpStatus(), errorCode.getMessage(), errorCode.getCode()); }backend/src/main/java/endolphin/backend/global/util/Validator.java (1)
11-27: Consider reducing code duplication using generics.The three validation methods share identical logic but operate on different temporal types. Consider using generics with a common interface like
Comparableto reduce duplication.- public static void validateDateTimeRange(LocalDateTime start, LocalDateTime end) { - if (end.isBefore(start)) { - throw new ApiException(ErrorCode.INVALID_DATE_TIME_RANGE); - } - } - - public static void validateDateTimeRange(LocalDate start, LocalDate end) { - if (end.isBefore(start)) { - throw new ApiException(ErrorCode.INVALID_DATE_TIME_RANGE); - } - } - - public static void validateDateTimeRange(LocalTime start, LocalTime end) { - if (end.isBefore(start)) { - throw new ApiException(ErrorCode.INVALID_DATE_TIME_RANGE); - } - } + public static <T extends Comparable<T>> void validateDateTimeRange(T start, T end) { + if (start.compareTo(end) > 0) { + throw new ApiException(ErrorCode.INVALID_DATE_TIME_RANGE); + } + }backend/src/test/java/endolphin/backend/global/util/ValidatorTest.java (1)
22-30: Enhance test coverage and assertions.
- Add test cases for
LocalDateandLocalTimevalidation.- Verify the specific error code in the caught exception.
@Test @DisplayName("시간 범위 체크 예외 테스트") void validateDateTimeRangeTest_Failure() { LocalDateTime startTime = LocalDateTime.of(2020, 12, 31, 23, 59, 59); LocalDateTime endTime = LocalDateTime.of(2020, 10, 31, 23, 59, 59); assertThatThrownBy(() -> Validator.validateDateTimeRange(startTime, endTime)) - .isInstanceOf(ApiException.class); + .isInstanceOf(ApiException.class) + .hasFieldOrPropertyWithValue("errorCode", ErrorCode.INVALID_DATE_TIME_RANGE); } + + @Test + @DisplayName("날짜 범위 체크 예외 테스트") + void validateDateRangeTest_Failure() { + LocalDate startDate = LocalDate.of(2020, 12, 31); + LocalDate endDate = LocalDate.of(2020, 10, 31); + + assertThatThrownBy(() -> Validator.validateDateTimeRange(startDate, endDate)) + .isInstanceOf(ApiException.class) + .hasFieldOrPropertyWithValue("errorCode", ErrorCode.INVALID_DATE_TIME_RANGE); + } + + @Test + @DisplayName("시각 범위 체크 예외 테스트") + void validateTimeRangeTest_Failure() { + LocalTime startTime = LocalTime.of(23, 59, 59); + LocalTime endTime = LocalTime.of(22, 59, 59); + + assertThatThrownBy(() -> Validator.validateDateTimeRange(startTime, endTime)) + .isInstanceOf(ApiException.class) + .hasFieldOrPropertyWithValue("errorCode", ErrorCode.INVALID_DATE_TIME_RANGE); + }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (12)
backend/build.gradle(1 hunks)backend/src/main/java/endolphin/backend/domain/discussion/DiscussionController.java(1 hunks)backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java(5 hunks)backend/src/main/java/endolphin/backend/domain/user/UserController.java(1 hunks)backend/src/main/java/endolphin/backend/domain/user/UserService.java(3 hunks)backend/src/main/java/endolphin/backend/domain/user/entity/User.java(2 hunks)backend/src/main/java/endolphin/backend/global/error/ErrorResponse.java(1 hunks)backend/src/main/java/endolphin/backend/global/error/GlobalExceptionHandler.java(1 hunks)backend/src/main/java/endolphin/backend/global/error/exception/ErrorCode.java(1 hunks)backend/src/main/java/endolphin/backend/global/util/Validator.java(2 hunks)backend/src/test/java/endolphin/backend/domain/user/UserServiceTest.java(1 hunks)backend/src/test/java/endolphin/backend/global/util/ValidatorTest.java(2 hunks)
🧰 Additional context used
📓 Learnings (1)
backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java (1)
Learnt from: kwon204
PR: softeer5th/Team4-enDolphin#45
File: backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java:28-33
Timestamp: 2025-02-04T01:27:54.848Z
Learning: For search/filter operations in REST APIs, prefer using GET with query parameters over POST with request body, as it follows REST principles and enables caching, bookmarking, and better API discoverability.
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Send PR Notification to Reviewers
🔇 Additional comments (10)
backend/src/main/java/endolphin/backend/domain/user/entity/User.java (1)
31-34: LGTM! Good use of @column for DB compatibility.The renaming of token fields to camelCase while maintaining snake_case DB column names through
@Columnannotations is a good practice. This maintains Java naming conventions in the code while preserving backward compatibility with the database schema.backend/src/test/java/endolphin/backend/domain/user/UserServiceTest.java (1)
86-88: LGTM! Test updated consistently with entity changes.The builder calls have been correctly updated to use the new camelCase token field names.
backend/src/main/java/endolphin/backend/domain/user/UserService.java (1)
66-67: LGTM! Consistent with entity changes.The token field references have been correctly updated to use camelCase naming.
backend/src/main/java/endolphin/backend/global/error/ErrorResponse.java (1)
7-14: LGTM! Well-documented error response structure.The Swagger annotations provide clear descriptions and examples for each field, making the API documentation comprehensive and user-friendly.
backend/src/main/java/endolphin/backend/global/error/exception/ErrorCode.java (1)
10-10: LGTM! Well-structured error code for date/time validation.The new error code follows the established pattern and uses appropriate HTTP status code for validation errors.
backend/src/main/java/endolphin/backend/domain/discussion/DiscussionController.java (1)
6-7: LGTM! Clear and well-documented API annotations.The Swagger annotations provide clear documentation in Korean, making the API more accessible and understandable.
Also applies to: 14-14, 22-22
backend/src/main/java/endolphin/backend/global/error/GlobalExceptionHandler.java (1)
20-20: Verify error response structure consistency.The HTTP status is now retrieved from the response object instead of directly from the error code. Ensure that all ErrorResponse instances properly initialize their httpStatus field.
✅ Verification successful
🏁 Script executed:
#!/bin/bash # Search for all ErrorResponse.of() calls to verify proper HTTP status initialization ast-grep --pattern 'ErrorResponse.of($$$)'Length of output: 358
Consistent ErrorResponse HTTP status initialization verified.
Both calls in GlobalExceptionHandler.java (lines 19 and 26) useErrorResponse.of(...)with anErrorCodeargument, which—as implied by the new retrieval strategy—should encapsulate the HTTP status. Verify that theErrorResponse.of()implementation consistently takes the provided error code and sets itshttpStatusfield accordingly.backend/src/main/java/endolphin/backend/domain/user/UserController.java (1)
5-6: LGTM! Well-documented authentication endpoints.The Swagger annotations clearly document the authentication flow in Korean, improving API usability.
Also applies to: 13-13, 20-20, 27-27
backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java (1)
6-13: LGTM! Comprehensive API documentation with detailed response scenarios.The Swagger annotations provide thorough documentation in Korean, with well-defined response scenarios and status codes.
Also applies to: 31-31, 39-49
backend/build.gradle (1)
48-48: Updated Swagger Dependency Version
Thespringdoc-openapi-starter-webmvc-uidependency version has been updated from2.6.0to2.8.4. This update should bring in the latest features and bug fixes related to Swagger annotations and API documentation. Please verify that all Swagger annotations in your controllers remain compatible with this new version and that any configuration adjustments required by the newer version have been addressed.
| @ApiResponse(responseCode = "200", description = "일정 조회 성공", | ||
| useReturnTypeSchema = true), |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix response code documentation for createPersonalEvent.
The success response code should be 201 (Created) instead of 200 (OK) since this is a resource creation endpoint.
- @ApiResponse(responseCode = "200", description = "일정 조회 성공",
+ @ApiResponse(responseCode = "201", description = "일정 생성 성공",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| @ApiResponse(responseCode = "200", description = "일정 조회 성공", | |
| useReturnTypeSchema = true), | |
| @ApiResponse(responseCode = "201", description = "일정 생성 성공", | |
| useReturnTypeSchema = true), |
| @Schema(description = "에러 응답") | ||
| public record ErrorResponse( | ||
| @Schema(description = "상태코드", example = "500") | ||
| HttpStatus httpStatus, |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java (1)
40-52: Enhance array schema documentation for better clarity.While the documentation is comprehensive, the array schema could be more specific about the
ListResponsewrapper.Update the content annotation to explicitly show the
ListResponsewrapper:@ApiResponse(responseCode = "200", description = "일정 조회 성공", content = @Content( - array = @ArraySchema( - schema = @Schema(implementation = PersonalEventResponse.class)))), + schema = @Schema( + implementation = ListResponse.class, + subTypes = {PersonalEventResponse.class}))),
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
backend/src/main/java/endolphin/backend/domain/discussion/DiscussionController.java(1 hunks)backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java(5 hunks)backend/src/main/java/endolphin/backend/global/error/ErrorResponse.java(1 hunks)backend/src/main/java/endolphin/backend/global/error/GlobalExceptionHandler.java(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- backend/src/main/java/endolphin/backend/global/error/GlobalExceptionHandler.java
- backend/src/main/java/endolphin/backend/domain/discussion/DiscussionController.java
- backend/src/main/java/endolphin/backend/global/error/ErrorResponse.java
🧰 Additional context used
📓 Learnings (1)
backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java (1)
Learnt from: kwon204
PR: softeer5th/Team4-enDolphin#45
File: backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java:28-33
Timestamp: 2025-02-04T01:27:54.848Z
Learning: For search/filter operations in REST APIs, prefer using GET with query parameters over POST with request body, as it follows REST principles and enables caching, bookmarking, and better API discoverability.
🔇 Additional comments (4)
backend/src/main/java/endolphin/backend/domain/personal_event/PersonalEventController.java (4)
6-14: LGTM! Well-structured Swagger documentation setup.The imports and class-level Swagger annotations are properly organized, with appropriate tag name and description in Korean.
Also applies to: 32-32
62-79: LGTM! Excellent REST implementation for resource creation.The endpoint follows REST best practices with proper 201 status code, location header, and response body.
81-101: LGTM! Well-documented update endpoint.The endpoint follows REST conventions with appropriate status codes and comprehensive error documentation.
103-120: LGTM! Proper implementation of DELETE endpoint.The endpoint follows REST conventions with appropriate 204 status code and comprehensive error documentation.
#️⃣ 연관된 이슈>
📝 작업 내용> 이번 PR에서 작업한 내용을 간략히 설명해주세요(이미지 첨부 가능)
Controller에 Swagger 관련 Annotation을 추가했습니다
기타 버그도 수정했습니다.
🙏 여기는 꼭 봐주세요! > 리뷰어가 특별히 봐주었으면 하는 부분이 있다면 작성해주세요
Summary by CodeRabbit