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

src/main/java/com/dduru/gildongmu/S3/controller/S3ApiDocs.java

@@ -2,10 +2,10 @@
 
 import com.dduru.gildongmu.S3.dto.ImageUploadRequest;
 import com.dduru.gildongmu.S3.dto.ImageUploadResponse;
+import com.dduru.gildongmu.common.annotation.ApiErrorResponses;
 import com.dduru.gildongmu.common.dto.ApiResult;
+import com.dduru.gildongmu.common.exception.ErrorCode;
 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 org.springframework.http.ResponseEntity;
@@ -16,8 +16,10 @@ public interface S3ApiDocs {
 
     @Operation(summary = "이미지 업로드를 위한 Presigned URL 생성",
                description = "S3에 이미지를 직접 업로드하기 위한 Presigned URL을 생성합니다.")
-    @ApiResponse(responseCode = "200", description = "Presigned URL 생성 성공",
-            content = @Content(mediaType = "application/json",
-            schema = @Schema(implementation = ImageUploadResponse.class)))
+    @ApiResponse(responseCode = "200", description = "Presigned URL 생성 성공")
+    @ApiErrorResponses({
+            ErrorCode.INVALID_INPUT_VALUE,
+            ErrorCode.INVALID_FILE_EXTENSION
+    })
     ResponseEntity<ApiResult<ImageUploadResponse>> prepareUpload(@RequestBody ImageUploadRequest request);
 }

src/main/java/com/dduru/gildongmu/auth/controller/OauthApiDocs.java

@@ -3,11 +3,13 @@
 import com.dduru.gildongmu.auth.dto.LoginRequest;
 import com.dduru.gildongmu.auth.dto.LoginResponse;
 import com.dduru.gildongmu.auth.dto.RefreshTokenRequest;
+import com.dduru.gildongmu.common.annotation.ApiErrorResponses;
 import com.dduru.gildongmu.common.dto.ApiResult;
+import com.dduru.gildongmu.common.exception.ErrorCode;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
 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.validation.Valid;
@@ -18,27 +20,30 @@
 public interface OauthApiDocs {
 
     @Operation(summary = "ID Token 로그인 (모바일)", description = "ID Token을 사용한 OAuth 로그인을 처리합니다.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "로그인 성공"),
-            @ApiResponse(responseCode = "400", description = "잘못된 요청"),
-            @ApiResponse(responseCode = "401", description = "유효하지 않은 ID Token")
+    @ApiResponse(responseCode = "200", description = "로그인 성공")
+    @ApiErrorResponses({
+            ErrorCode.INVALID_INPUT_VALUE,
+            ErrorCode.UNSUPPORTED_SOCIAL_LOGIN,
+            ErrorCode.SOCIAL_LOGIN_FAILED,
+            ErrorCode.INVALID_TOKEN,
+            ErrorCode.DUPLICATE_EMAIL
     })
     ResponseEntity<ApiResult<LoginResponse>> loginWithIdToken(
             @Parameter(description = "OAuth Provider (kakao, google)", example = "kakao") String provider,
             @RequestBody(required = false) LoginRequest request
     );
 
     @Operation(summary = "Access Token 갱신", description = "Refresh Token을 사용하여 Access Token을 갱신합니다.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "토큰 갱신 성공"),
-            @ApiResponse(responseCode = "400", description = "잘못된 Refresh Token")
+    @ApiResponse(responseCode = "200", description = "토큰 갱신 성공")
+    @ApiErrorResponses({
+            ErrorCode.INVALID_INPUT_VALUE,
+            ErrorCode.INVALID_TOKEN,
+            ErrorCode.EXPIRED_TOKEN
     })
     ResponseEntity<ApiResult<LoginResponse>> refreshAccessToken(@Valid RefreshTokenRequest request);
 
     @Operation(summary = "로그아웃", description = "사용자 로그아웃을 처리합니다.", security = @SecurityRequirement(name = "JWT"))
-    @ApiResponses({
-            @ApiResponse(responseCode = "204", description = "로그아웃 성공"),
-            @ApiResponse(responseCode = "401", description = "인증되지 않은 사용자")
-    })
+    @ApiResponse(responseCode = "204", description = "로그아웃 성공", content = @Content())
+    @ApiErrorResponses({ErrorCode.UNAUTHORIZED, ErrorCode.INVALID_TOKEN, ErrorCode.EXPIRED_TOKEN})
     ResponseEntity<ApiResult<Void>> logout(@Parameter(hidden = true) Long userId);
 }

src/main/java/com/dduru/gildongmu/comment/controller/CommentApiDocs.java

@@ -3,11 +3,13 @@
 import com.dduru.gildongmu.comment.dto.CommentCreateRequest;
 import com.dduru.gildongmu.comment.dto.CommentResponse;
 import com.dduru.gildongmu.comment.dto.CommentUpdateRequest;
+import com.dduru.gildongmu.common.annotation.ApiErrorResponses;
 import com.dduru.gildongmu.common.dto.ApiResult;
+import com.dduru.gildongmu.common.exception.ErrorCode;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
 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 jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
@@ -17,10 +19,14 @@
 @Tag(name = "Comments", description = "댓글 API")
 public interface CommentApiDocs {
     @Operation(summary = "댓글 작성", description = "게시글에 새로운 댓글을 작성합니다.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "201", description = "작성 성공"),
-            @ApiResponse(responseCode = "400", description = "잘못된 요청"),
-            @ApiResponse(responseCode = "404", description = "게시글 또는 부모 댓글을 찾을 수 없음")
+    @ApiResponse(responseCode = "201", description = "작성 성공")
+    @ApiErrorResponses({
+            ErrorCode.INVALID_INPUT_VALUE,
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.COMMENT_NOT_FOUND,
+            ErrorCode.INVALID_PARENT_COMMENT,
+            ErrorCode.USER_NOT_FOUND,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<CommentResponse>> createComment(
             @Parameter(hidden = true) Long userId,
@@ -29,18 +35,20 @@ ResponseEntity<ApiResult<CommentResponse>> createComment(
     );
 
     @Operation(summary = "게시글 댓글 조회", description = "특정 게시글의 모든 댓글을 조회합니다. 대댓글 포함 계층 구조로 반환됩니다.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "조회 성공"),
-            @ApiResponse(responseCode = "404", description = "게시글을 찾을 수 없음")
-    })
+    @ApiResponse(responseCode = "200", description = "조회 성공")
+    @ApiErrorResponses({ErrorCode.POST_NOT_FOUND})
     ResponseEntity<ApiResult<List<CommentResponse>>> retrieveComments(
             @Parameter(description = "게시글 ID") Long postId
     );
 
     @Operation(summary = "댓글 삭제", description = "특정 게시글의 댓글을 삭제합니다.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "204", description = "삭제 성공"),
-            @ApiResponse(responseCode = "404", description = "게시글 또는 댓글을 찾을 수 없음")
+    @ApiResponse(responseCode = "204", description = "삭제 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.COMMENT_NOT_FOUND,
+            ErrorCode.COMMENT_ACCESS_DENIED,
+            ErrorCode.INVALID_PARENT_COMMENT,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<Void>> deleteComment(
             @Parameter(hidden = true) Long userId,
@@ -49,9 +57,14 @@ ResponseEntity<ApiResult<Void>> deleteComment(
     );
 
     @Operation(summary = "댓글 수정", description = "특정 게시글의 댓글을 수정합니다.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "204", description = "수정 성공"),
-            @ApiResponse(responseCode = "404", description = "게시글 또는 댓글을 찾을 수 없음")
+    @ApiResponse(responseCode = "204", description = "수정 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.INVALID_INPUT_VALUE,
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.COMMENT_NOT_FOUND,
+            ErrorCode.COMMENT_ACCESS_DENIED,
+            ErrorCode.INVALID_PARENT_COMMENT,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<Void>> updateComment(
             @Parameter(hidden = true) Long userId,

src/main/java/com/dduru/gildongmu/like/controller/CommentLikeApiDocs.java

@@ -1,9 +1,12 @@
 package com.dduru.gildongmu.like.controller;
 
+import com.dduru.gildongmu.common.annotation.ApiErrorResponses;
 import com.dduru.gildongmu.common.annotation.CurrentUser;
 import com.dduru.gildongmu.common.dto.ApiResult;
+import com.dduru.gildongmu.common.exception.ErrorCode;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
@@ -12,6 +15,11 @@
 @Tag(name = "Comments", description = "댓글 좋아요 관련 API")
 public interface CommentLikeApiDocs {
     @Operation(summary = "댓글 좋아요 토글", description = "댓글에 대한 좋아요를 추가하거나 삭제합니다.")
-    @ApiResponse(responseCode = "204", description = "좋아요 토글 성공")
+    @ApiResponse(responseCode = "204", description = "좋아요 토글 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.COMMENT_NOT_FOUND,
+            ErrorCode.USER_NOT_FOUND,
+            ErrorCode.UNAUTHORIZED
+    })
     ResponseEntity<ApiResult<Void>> toggleCommentLike(@Parameter(hidden = true) @CurrentUser Long userId, @PathVariable Long commentId);
 }

src/main/java/com/dduru/gildongmu/like/controller/PostLikeApiDocs.java

@@ -1,9 +1,12 @@
 package com.dduru.gildongmu.like.controller;
 
+import com.dduru.gildongmu.common.annotation.ApiErrorResponses;
 import com.dduru.gildongmu.common.annotation.CurrentUser;
 import com.dduru.gildongmu.common.dto.ApiResult;
+import com.dduru.gildongmu.common.exception.ErrorCode;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
@@ -12,6 +15,11 @@
 @Tag(name = "Posts", description = "게시글 좋아요 관련 API")
 public interface PostLikeApiDocs {
     @Operation(summary = "게시글 좋아요 토글", description = "게시글에 대한 좋아요를 추가하거나 삭제합니다.")
-    @ApiResponse(responseCode = "204", description = "좋아요 토글 성공")
+    @ApiResponse(responseCode = "204", description = "좋아요 토글 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.USER_NOT_FOUND,
+            ErrorCode.UNAUTHORIZED
+    })
     ResponseEntity<ApiResult<Void>> togglePostLike(@Parameter(hidden = true) @CurrentUser Long userId, @PathVariable Long postId);
 }

src/main/java/com/dduru/gildongmu/participation/controller/ParticipationApiDocs.java

@@ -1,12 +1,14 @@
 package com.dduru.gildongmu.participation.controller;
 
+import com.dduru.gildongmu.common.annotation.ApiErrorResponses;
 import com.dduru.gildongmu.common.dto.ApiResult;
+import com.dduru.gildongmu.common.exception.ErrorCode;
 import com.dduru.gildongmu.participation.dto.ParticipationRequest;
 import com.dduru.gildongmu.participation.dto.ParticipationResponse;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
 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.validation.Valid;
@@ -19,8 +21,15 @@
 public interface ParticipationApiDocs {
 
     @Operation(summary = "참여 신청", description = "게시글에 참여 신청을 합니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "201", description = "참여 신청 성공"),
+    @ApiResponse(responseCode = "201", description = "참여 신청 성공")
+    @ApiErrorResponses({
+            ErrorCode.INVALID_INPUT_VALUE,
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.RECRUITMENT_CLOSED,
+            ErrorCode.DUPLICATE_PARTICIPATION,
+            ErrorCode.SELF_PARTICIPATION_NOT_ALLOWED,
+            ErrorCode.USER_NOT_FOUND,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<ParticipationResponse>> createParticipation(
             @Parameter(description = "게시글 ID") Long postId,
@@ -29,17 +38,26 @@ ResponseEntity<ApiResult<ParticipationResponse>> createParticipation(
     );
 
     @Operation(summary = "게시글 참여자 목록 조회", description = "게시글에 참여한 사용자 목록을 조회합니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "참여자 목록 조회 성공"),
+    @ApiResponse(responseCode = "200", description = "참여자 목록 조회 성공")
+    @ApiErrorResponses({
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.POST_ACCESS_DENIED,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<List<ParticipationResponse>>> getPostParticipants(
             @Parameter(description = "게시글 ID") Long postId,
             @Parameter(hidden = true) Long userId
     );
 
     @Operation(summary = "참여 신청 승인", description = "게시글 참여 신청을 승인합니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "참여 신청 승인 성공"),
+    @ApiResponse(responseCode = "204", description = "참여 신청 승인 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.PARTICIPATION_NOT_FOUND,
+            ErrorCode.POST_ACCESS_DENIED,
+            ErrorCode.PARTICIPATION_POST_MISMATCH,
+            ErrorCode.RECRUIT_COUNT_EXCEED_CAPACITY,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<Void>> approveParticipation(
             @Parameter(description = "게시글 ID") Long postId,
@@ -48,8 +66,13 @@ ResponseEntity<ApiResult<Void>> approveParticipation(
     );
 
     @Operation(summary = "참여 신청 거절", description = "게시글 참여 신청을 거절합니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "참여 신청 거절 성공"),
+    @ApiResponse(responseCode = "204", description = "참여 신청 거절 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.PARTICIPATION_NOT_FOUND,
+            ErrorCode.POST_ACCESS_DENIED,
+            ErrorCode.PARTICIPATION_POST_MISMATCH,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<Void>> rejectParticipation(
             @Parameter(description = "게시글 ID") Long postId,
@@ -58,8 +81,14 @@ ResponseEntity<ApiResult<Void>> rejectParticipation(
     );
 
     @Operation(summary = "참여 취소", description = "게시글 참여를 취소합니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "204", description = "참여 취소 성공"),
+    @ApiResponse(responseCode = "204", description = "참여 취소 성공", content = @Content())
+    @ApiErrorResponses({
+            ErrorCode.POST_NOT_FOUND,
+            ErrorCode.PARTICIPATION_NOT_FOUND,
+            ErrorCode.POST_ACCESS_DENIED,
+            ErrorCode.PARTICIPATION_POST_MISMATCH,
+            ErrorCode.RECRUIT_COUNT_BELOW_ZERO,
+            ErrorCode.UNAUTHORIZED
     })
     ResponseEntity<ApiResult<Void>> cancelParticipation(
             @Parameter(description = "게시글 ID") Long postId,