docs: Swagger UI 문서 전면 개선 - 에러 응답 자동화, 스키마 수정, 204 응답 개선

[shinheekim]

🔎 작업 내용

• 모든 ApiDocs에 @ApiErrorResponses 어노테이션 추가하여 실제 에러 처리와 일치하도록 개선
• 잘못 정의된 응답 스키마 수정 (S3ApiDocs, SurveyApiDocs, ProfileApiDocs, PhoneVerificationApiDocs)
• 204 No Content 응답에 대해 Swagger UI에서 body 예시가 표시되지 않도록 content = @Content() 추가
• 성공 응답 상태코드와 실제 응답 검토 및 일치 여부 확인

➕ 이슈 링크

• Closed [DOCS] 전체 컨트롤러에 대한 에러 응답 커스텀 적용 #131

📸 스크린샷

성공 응답

• 200 OK

• 204 NO CONTENT

• 에러 응답 예시

😎 리뷰 요구사항

• 모든 에러 응답이 @ApiErrorResponses를 통해 자동으로 생성되도록 통일했습니다.
• 204 응답의 경우 프론트 개발자가 혼동하지 않도록 body 예시가 표시되지 않도록 수정했습니다.
• 실제 컨트롤러 구현과 Swagger 문서가 일치하는지 전체적으로 검토했습니다.

🧑‍💻 예정 작업

• issue 추가 후 수정할 예정

📝 체크리스트

• 브랜치 이름은 feature/개발내용 형식으로 작성했는가?
• 커밋 메시지는 feat: 커밋 내용 형식으로 작성했는가?
• 작업 전 Issue를 작성했는가?
• dev 브랜치로 병합을 요청했는가?
• 불필요한 주석과 공백은 제거했는가?
• 코드 리뷰어의 피드백을 반영했는가?
• 테스트를 진행했는가?
• 테스트 코드를 작성했는가?

[Copilot]

Pull request overview

This PR standardizes Swagger/OpenAPI documentation by replacing manual error response definitions with the @ApiErrorResponses annotation across API documentation interfaces. The changes improve consistency and maintainability by automatically generating error responses from ErrorCode enums.

Key changes:

• Introduced @ApiErrorResponses annotation to automatically generate error response documentation from ErrorCode enums across all API documentation interfaces
• Fixed incorrect response schemas by removing redundant manual schema definitions that conflicted with automatic generation
• Added content = @Content() to 204 No Content responses to prevent Swagger UI from displaying misleading body examples
• Corrected SurveyController to use ApiResult.created() instead of ApiResult.ok() for 201 responses, ensuring the internal status field matches the HTTP status code

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
PhoneVerificationApiDocs.java	Replaced verbose manual error responses with @ApiErrorResponses annotation for verification code sending and verification endpoints
SurveyController.java	Fixed inconsistency by using ApiResult.created() for 201 status and simplified 200 OK response creation
SurveyApiDocs.java	Removed redundant schema definitions from success responses to allow automatic generation
ProfileApiDocs.java	Added content = @Content() to 204 responses and replaced manual error definitions with @ApiErrorResponses
PostApiDocs.java	Replaced wildcard imports with explicit imports, added @ApiErrorResponses for all endpoints, and ensured 204 responses have empty content
ParticipationApiDocs.java	Migrated all endpoints to use @ApiErrorResponses and added content = @Content() to 204 responses
PostLikeApiDocs.java	Added @ApiErrorResponses for toggle endpoint and fixed 204 response content
CommentLikeApiDocs.java	Added @ApiErrorResponses for toggle endpoint and fixed 204 response content
CommentApiDocs.java	Replaced manual error responses with @ApiErrorResponses for create, retrieve, delete, and update operations
OauthApiDocs.java	Migrated authentication endpoints to use @ApiErrorResponses and fixed 204 logout response
S3ApiDocs.java	Removed redundant schema definition and added @ApiErrorResponses for file upload endpoint

Comments suppressed due to low confidence (1)

src/main/java/com/dduru/gildongmu/survey/controller/SurveyApiDocs.java:114

• The SurveyApiDocs interface was not updated to use the new @ApiErrorResponses annotation pattern like other ApiDocs files. According to the PR description, all ApiDocs should be migrated to use @ApiErrorResponses for consistency. This file still uses the old manual @ApiResponses with detailed error examples.

Consider updating this file to follow the same pattern as other ApiDocs:

• Replace the manual error response definitions with @ApiErrorResponses annotations
• For the submitSurvey method, add error codes like ErrorCode.INVALID_INPUT_VALUE
• For the getMySurveyResult method, add error codes like ErrorCode.SURVEY_RESULT_NOT_FOUND and ErrorCode.UNAUTHORIZED

    @ApiResponses({
            @ApiResponse(
                    responseCode = "201",
                    description = "설문 제출 성공"
            ),
            @ApiResponse(
                    responseCode = "400",
                    description = "잘못된 요청 (유효하지 않은 답변 코드, 필수 질문 미응답, Q7 범위 초과 등)",
                    content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = ErrorResponse.class),
                            examples = {
                                    @ExampleObject(
                                            name = "InvalidAnswerCode",
                                            value = """
                                                    {
                                                      "status": 400,
                                                      "data": {
                                                        "errorCode": "INVALID_INPUT_VALUE",
                                                        "field": null,
                                                        "message": "Q1 이동수단에 대한 유효하지 않은 답변 코드입니다: 99"
                                                      }
                                                    }
                                                    """
                                    ),
                                    @ExampleObject(
                                            name = "ValidationError",
                                            value = """
                                                    {
                                                      "status": 400,
                                                      "data": {
                                                        "errorCode": "INVALID_INPUT_VALUE",
                                                        "field": "q1",
                                                        "message": "Q1 이동수단은 필수입니다."
                                                      }
                                                    }
                                                    """
                                    ),
                                    @ExampleObject(
                                            name = "InvalidQ7Size",
                                            value = """
                                                    {
                                                      "status": 400,
                                                      "data": {
                                                        "errorCode": "INVALID_INPUT_VALUE",
                                                        "field": "q7",
                                                        "message": "Q7 선호활동은 최대 3개까지 선택할 수 있습니다."
                                                      }
                                                    }
                                                    """
                                    )
                            }
                    )
            )
    })
    ResponseEntity<ApiResult<SurveyResponse>> submitSurvey(
            @Parameter(hidden = true) Long userId,
            @Valid SurveyRequest request
    );

    @Operation(summary = "내 설문 결과 조회", description = "현재 사용자의 설문 결과 및 매칭된 아바타를 조회합니다.")
    @ApiResponses({
            @ApiResponse(
                    responseCode = "200",
                    description = "조회 성공"
            ),
            @ApiResponse(
                    responseCode = "404",
                    description = "설문 결과를 찾을 수 없음",
                    content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = ErrorResponse.class),
                            examples = @ExampleObject(
                                    name = "SurveyResultNotFound",
                                    value = """
                                            {
                                              "status": 404,
                                              "data": {
                                                "errorCode": "SURVEY_RESULT_NOT_FOUND",
                                                "field": null,
                                                "message": "설문 결과를 찾을 수 없습니다."
                                              }
                                            }
                                            """
                            )
                    )
            )
    })
    ResponseEntity<ApiResult<SurveyResponse>> getMySurveyResult(
            @Parameter(hidden = true) Long userId
    );

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jaejoong0529]

수고하셨습니당