[REFACTOR/#504] 에러코드를 Swagger 문서에 자동으로 노출하도록 개선

src/main/java/com/assu/server/domain/admin/controller/AdminController.java

@@ -4,6 +4,8 @@
 import com.assu.server.domain.admin.service.AdminService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import com.assu.server.global.util.PrincipalDetails;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -35,6 +37,7 @@ public class AdminController {
                     "  - `partnerName` (String): 제휴업체 상호명\n" +
                     "  - `partnerUrl` (String): 제휴업체 프로필 이미지 URL (S3 주소)\n" +
                     "  - `partnerPhone` (String): 제휴업체 전화번호\n")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.ADMIN_PARTNER_RECOMMEND)
     @GetMapping("/partner-recommend")
     public BaseResponse<AdminResponseDTO> randomPartnerRecommend(
             @AuthenticationPrincipal PrincipalDetails pd

src/main/java/com/assu/server/domain/admin/controller/StudentAdminController.java

@@ -4,6 +4,8 @@
 import com.assu.server.domain.admin.service.StudentAdminService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import com.assu.server.global.util.PrincipalDetails;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -28,6 +30,7 @@ public class StudentAdminController {
             description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24c1197c19ed8062be94fc08619b760f)\n" +
                     "- 관리자(Admin) 권한으로 접근하여 현재까지의 총 누적 가입자 수를 조회합니다."
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.ADMIN_DASHBOARD_COUNT_ADMIN)
     @GetMapping
     public BaseResponse<StudentAdminResponseDTO.CountAdminAuthResponseDTO> getCountAdmin(
             @AuthenticationPrincipal PrincipalDetails pd
@@ -40,6 +43,7 @@ public BaseResponse<StudentAdminResponseDTO.CountAdminAuthResponseDTO> getCountA
             description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24c1197c19ed805db80fca98c38849d1)\n" +
                     "- 이번 달(매달 1일 초기화) 기준 신규 가입한 사용자 수를 조회합니다."
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.ADMIN_DASHBOARD_NEW_STUDENT_COUNT)
     @GetMapping("/new")
     public BaseResponse<StudentAdminResponseDTO.NewCountAdminResponseDTO> getNewStudentCountAdmin(
             @AuthenticationPrincipal PrincipalDetails pd
@@ -52,6 +56,7 @@ public BaseResponse<StudentAdminResponseDTO.NewCountAdminResponseDTO> getNewStud
             description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24e1197c19ed80a283b1c336a1c3df72)\n" +
                     "- 금일 제휴 서비스를 이용한 총 사용자 수를 조회합니다."
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.ADMIN_DASHBOARD_COUNT_USER)
     @GetMapping("/countUser")
     public BaseResponse<StudentAdminResponseDTO.CountUsagePersonResponseDTO> getCountUser(
             @AuthenticationPrincipal PrincipalDetails pd
@@ -64,6 +69,7 @@ public BaseResponse<StudentAdminResponseDTO.CountUsagePersonResponseDTO> getCoun
             description = "# [v1.0 (2025-09-02)](https://www.notion.so/_1-2ef1197c19ed8010a49ce6313d137b4f)\n" +
                     "- 제휴 이용 횟수가 가장 많은 1위 업체의 정보를 조회합니다."
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.ADMIN_DASHBOARD_TOP_USAGE)
     @GetMapping("/top")
     public BaseResponse<StudentAdminResponseDTO.CountUsageResponseDTO> getTopUsage(
             @AuthenticationPrincipal PrincipalDetails pd
@@ -76,6 +82,7 @@ public BaseResponse<StudentAdminResponseDTO.CountUsageResponseDTO> getTopUsage(
             description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24e1197c19ed802b92eff5d4dc4dbe82)\n" +
                     "- 모든 제휴 업체의 누적 사용 현황을 사용량 내림차순 리스트로 반환합니다."
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.ADMIN_DASHBOARD_USAGE_LIST)
     @GetMapping("/usage")
     public BaseResponse<StudentAdminResponseDTO.CountUsageListResponseDTO> getUsageList(
             @AuthenticationPrincipal PrincipalDetails pd

src/main/java/com/assu/server/domain/appreview/controller/AppReviewController.java

@@ -4,6 +4,8 @@
 import com.assu.server.domain.appreview.service.AppReviewService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import com.assu.server.global.util.PrincipalDetails;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.media.Content;
@@ -38,6 +40,7 @@ public class AppReviewController {
                     "\n**Response:**\n" +
                     "  - 성공 시 200(OK)과 성공 메시지 반환"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.APP_REVIEW_CREATE)
     @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
     public BaseResponse<Void> createAppReview(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(

src/main/java/com/assu/server/domain/auth/controller/AuthController.java

@@ -25,6 +25,8 @@
 import com.assu.server.domain.common.entity.enums.University;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.enums.ParameterIn;
@@ -66,6 +68,7 @@ public class AuthController {
                     "\n**Response:**\n" +
                     "  - 성공 시 200(OK)과 성공 메시지 반환"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_PHONE_SEND_CODE)
     @PostMapping("/phone-verification/check-and-send")
     public BaseResponse<Void> checkPhoneAvailabilityAndSendAuthNumber(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -95,6 +98,7 @@ public BaseResponse<Void> checkPhoneAvailabilityAndSendAuthNumber(
                     "\n**Response:**\n" +
                     "  - 성공 시 200(OK)과 성공 메시지 반환"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_PHONE_VERIFY_CODE)
     @PostMapping("/phone-verification/verify")
     public BaseResponse<Void> checkAuthNumber(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -128,6 +132,7 @@ public BaseResponse<Void> checkAuthNumber(
                     "  - 성공 시 200(OK)과 사용 가능 메시지 반환\n" +
                     "  - 중복 시 404(NOT_FOUND)와 에러 메시지 반환"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_EMAIL_CHECK)
     @PostMapping("/email-verification/check")
     public BaseResponse<Void> checkEmailAvailability(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -175,6 +180,7 @@ public BaseResponse<Void> checkEmailAvailability(
                     "    - `department` (String): 단과대 (한글명)\n" +
                     "    - `major` (String): 전공/학과 (한글명)"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_SIGNUP_STUDENT)
     @PostMapping(value = "/students/signup", consumes = MediaType.APPLICATION_JSON_VALUE)
     public BaseResponse<SignUpResponseDTO> signupStudent(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -245,6 +251,7 @@ public BaseResponse<SignUpResponseDTO> signupStudent(
                     "    - `department` (String): null (Partner는 해당 없음)\n" +
                     "    - `major` (String): null (Partner는 해당 없음)"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_SIGNUP_PARTNER)
     @PostMapping(value = "/partners/signup", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
     public BaseResponse<SignUpResponseDTO> signupPartner(
             @RequestPart("request")
@@ -319,6 +326,7 @@ public BaseResponse<SignUpResponseDTO> signupPartner(
                     "    - `department` (String): 단과대 (한글명)\n" +
                     "    - `major` (String): 전공/학과 (한글명)"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_SIGNUP_ADMIN)
     @PostMapping(value = "/admins/signup", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
     public BaseResponse<SignUpResponseDTO> signupAdmin(
             @RequestPart("request")
@@ -373,6 +381,7 @@ public BaseResponse<SignUpResponseDTO> signupAdmin(
                     "  - 403(FORBIDDEN): `BACKOFFICE4003` — BACKOFFICE 계정은 `/auth/backoffice/login` 사용\n" +
                     "  - 401(UNAUTHORIZED): 이메일/비밀번호 불일치"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_LOGIN_COMMON)
     @PostMapping(value = "/commons/login", consumes = MediaType.APPLICATION_JSON_VALUE)
     public BaseResponse<LoginResponseDTO> loginCommon(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -414,6 +423,7 @@ public BaseResponse<LoginResponseDTO> loginCommon(
                     "    - `department` (String): 단과대 (한글명)\n" +
                     "    - `major` (String): 전공/학과 (한글명)"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_LOGIN_STUDENT)
     @PostMapping(value = "/students/login", consumes = MediaType.APPLICATION_JSON_VALUE)
     public BaseResponse<LoginResponseDTO> loginStudent(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -452,6 +462,7 @@ public BaseResponse<LoginResponseDTO> loginStudent(
                     "  - `newAccess` (String): 새로운 액세스 토큰\n" +
                     "  - `newRefresh` (String): 새로운 리프레시 토큰"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_TOKEN_REFRESH)
     @PostMapping("/tokens/refresh")
     public BaseResponse<RefreshResponseDTO> refreshToken(
             @Parameter(
@@ -475,6 +486,7 @@ public BaseResponse<RefreshResponseDTO> refreshToken(
                     "- 처리: Refresh 무효화(선택), Access 블랙리스트 등록.\n" +
                     "- 성공 시 200(OK)."
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_LOGOUT)
     @PostMapping("/logout")
     public BaseResponse<Void> logout(
             @Parameter(
@@ -513,6 +525,7 @@ public BaseResponse<Void> logout(
                     "  - `yearSemester` (String): 학년/학기\n" +
                     "  - `major` (Major enum): 전공/학과"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_SSU_VERIFY)
     @PostMapping(value = "/students/ssu-verify", consumes = MediaType.APPLICATION_JSON_VALUE)
     public BaseResponse<USaintAuthResponseDTO> ssuAuth(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -545,6 +558,7 @@ public BaseResponse<USaintAuthResponseDTO> ssuAuth(
                     "  - 성공 시 200(OK)과 성공 메시지 반환\n" +
                     "  - 유예기간 내 재로그인 및 재가입 시 계정 복구"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.AUTH_WITHDRAW)
     @PatchMapping("/withdraw")
     public BaseResponse<Void> withdrawMember(
             @Parameter(

src/main/java/com/assu/server/domain/auth/controller/BackofficeAuthController.java

@@ -6,6 +6,8 @@
 import com.assu.server.domain.auth.service.BackofficeAuthService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.enums.ParameterIn;
@@ -51,6 +53,7 @@ public class BackofficeAuthController {
                     "  - 403(FORBIDDEN): BACKOFFICE 역할이 아닌 계정\n" +
                     "  - 401(UNAUTHORIZED): 이메일 또는 비밀번호 불일치"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_AUTH_LOGIN)
     @PostMapping(value = "/login", consumes = MediaType.APPLICATION_JSON_VALUE)
     public BaseResponse<BackofficeLoginResponseDTO> login(
             @io.swagger.v3.oas.annotations.parameters.RequestBody(
@@ -85,6 +88,7 @@ public BaseResponse<BackofficeLoginResponseDTO> login(
                     "  - `newRefresh` (String): 새로운 리프레시 토큰\n" +
                     "  - 401(UNAUTHORIZED): audience 불일치 또는 유효하지 않은 Refresh Token"
     )
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_AUTH_REFRESH)
     @PostMapping("/tokens/refresh")
     public BaseResponse<RefreshResponseDTO> refresh(
             @Parameter(

src/main/java/com/assu/server/domain/backoffice/controller/BackofficeAdminController.java

@@ -6,6 +6,8 @@
 import com.assu.server.domain.backoffice.service.BackofficeMemberService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -38,6 +40,7 @@ public class BackofficeAdminController {
 					"- 403(FORBIDDEN): BACKOFFICE 권한 없음\n" +
 					"- 404(NOT_FOUND): Admin이 아니거나 인감 이미지 없음"
 	)
+	@ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_ADMIN_GET_SIGN_IMAGE)
 	@GetMapping("/{memberId}/sign-image")
 	public BaseResponse<BackofficeDocumentUrlResponseDTO> getSignImageUrl(
 			@Parameter(description = "Admin 회원 ID") @PathVariable Long memberId
@@ -72,6 +75,7 @@ public BaseResponse<BackofficeAdminFetchResponseDTO> fetchAdmin() {
 	}
 
 	@BackofficeAudited(action = "ADMIN_CREATE", targetId = "#req.email")
+	@ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_ADMIN_CREATE)
 	@Operation(
 			summary = "학생회 계정 임의 추가 API",
 			description = "인감 정보나 전화번호 없이 백오피스에서 임의로 학생회 계정을 추가합니다.\n\n" +
@@ -103,6 +107,7 @@ public BaseResponse<BackofficeAdminCreateResponseDTO> createAdmin(
 	}
 
 	@BackofficeAudited(action = "ADMIN_UPDATE", targetId = "#adminId")
+	@ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_ADMIN_UPDATE)
 	@Operation(
 			summary = "학생회 계정 임의 수정 API",
 			description = "학생회(Admin) 계정 정보를 수정합니다. 입력된 필드만 반영됩니다.\n\n" +
@@ -143,6 +148,7 @@ public BaseResponse<BackofficeAdminUpdateResponseDTO> updateAdmin(
 	}
 
 	@BackofficeAudited(action = "ADMIN_DELETE", targetId = "#adminId")
+	@ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_ADMIN_DELETE)
 	@Operation(
 			summary = "학생회 계정 임의 삭제 API",
 			description = "학생회(Admin) 계정과 이에 연관된 모든 데이터(Member, CommonAuth)를 영구 삭제합니다.\n\n" +

src/main/java/com/assu/server/domain/backoffice/controller/BackofficeChatController.java

@@ -5,6 +5,8 @@
 import com.assu.server.domain.backoffice.service.BackofficeChatBlockService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -22,6 +24,7 @@ public class BackofficeChatController {
     private final BackofficeChatBlockService backofficeChatBlockService;
 
     @BackofficeAudited(action = "CHAT_BLOCK_BETWEEN", targetId = "#request.blockerId() + '-' + #request.blockedId()")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_CHAT_BLOCK_BETWEEN)
     @Operation(
             summary = "두 멤버 간 채팅 차단 API",
             description = "- 특정 두 멤버 사이의 채팅을 차단합니다.\n" +
@@ -39,6 +42,7 @@ public BaseResponse<BackofficeChatBlockDTO.BlockBetweenMembersResponseDTO> block
     }
 
     @BackofficeAudited(action = "CHAT_UNBLOCK_BETWEEN", targetId = "#memberAId + '-' + #memberBId")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_CHAT_UNBLOCK_BETWEEN)
     @Operation(
             summary = "두 멤버 간 채팅 차단 해제 API",
             description = "- 특정 두 멤버 사이의 채팅 차단을 해제합니다.\n" +
@@ -57,6 +61,7 @@ public BaseResponse<BackofficeChatBlockDTO.BlockBetweenMembersResponseDTO> unblo
     }
 
     @BackofficeAudited(action = "CHAT_BLOCK_MEMBER", targetId = "#memberId")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_CHAT_BLOCK_MEMBER)
     @Operation(
             summary = "멤버 채팅 전체 차단 API",
             description = "- 특정 멤버의 채팅 기능 자체를 차단합니다.\n" +
@@ -73,6 +78,7 @@ public BaseResponse<BackofficeChatBlockDTO.MemberChatBlockResponseDTO> blockMemb
     }
 
     @BackofficeAudited(action = "CHAT_UNBLOCK_MEMBER", targetId = "#memberId")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_CHAT_UNBLOCK_MEMBER)
     @Operation(
             summary = "멤버 채팅 전체 차단 해제 API",
             description = "- 특정 멤버의 채팅 전체 차단을 해제합니다.\n" +

src/main/java/com/assu/server/domain/backoffice/controller/BackofficeDevSyncController.java

@@ -5,6 +5,8 @@
 import com.assu.server.domain.backoffice.service.BackofficeDevSyncService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
@@ -23,6 +25,7 @@ public class BackofficeDevSyncController {
     private final BackofficeDevSyncService backofficeDevSyncService;
 
     @BackofficeAudited(action = "DEV_SYNC")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_DEV_SYNC)
     @Operation(
             summary = "Prod DB → Dev DB 동기화 API",
             description = "# [v1.0 (2026-10-04)]\n" +

src/main/java/com/assu/server/domain/backoffice/controller/BackofficeHomeCurationController.java

@@ -16,6 +16,8 @@
 import com.assu.server.domain.backoffice.service.BackofficeHomeCurationService;
 import com.assu.server.global.apiPayload.BaseResponse;
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
+import com.assu.server.global.apiPayload.code.status.SwaggerErrorCodes;
+import com.assu.server.global.exception.annotation.ApiErrorCodeExamples;
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -44,6 +46,7 @@ public BaseResponse<BackofficeHomeCurationResponseDTO> getHomeCuration() {
     }
 
     @BackofficeAudited(action = "HOME_CURATION_UPDATE")
+    @ApiErrorCodeExamples(SwaggerErrorCodes.BACKOFFICE_HOME_CURATION_UPDATE)
     @Operation(
             summary = "전체 큐레이션 및 추천 업체 직접 저장 API (백오피스용)",
             description = "상단 추천 업체 및 2개 그룹(각 그룹당 2개 매장)을 직접 지정하여 저장합니다.\n\n" +