docs: Swagger(OpenAPI) API 문서 도입

build.gradle

@@ -36,6 +36,7 @@ dependencies {
     implementation 'org.springframework.boot:spring-boot-starter-log4j2'
     implementation 'io.jsonwebtoken:jjwt-api:0.12.6'
     implementation 'io.minio:minio:9.0.1'
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6'
     runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.6'
     runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.6'
     implementation 'org.flywaydb:flyway-core'

src/main/java/com/bop/youthpick/admin/board/controller/AdminCommunityCommentController.java

@@ -3,19 +3,23 @@
 import com.bop.youthpick.admin.board.dto.AdminCommunityCommentResponse;
 import com.bop.youthpick.admin.board.service.AdminCommunityService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 커뮤니티 댓글")
 @RestController
 @RequestMapping("/api/v1/admin/community-comments")
 @RequiredArgsConstructor
 public class AdminCommunityCommentController {
 
     private final AdminCommunityService adminCommunityService;
 
+    @Operation(summary = "커뮤니티 댓글 삭제", description = "관리자가 커뮤니티 댓글을 삭제합니다.")
     @DeleteMapping("/{commentId}")
     public ApiResponse<AdminCommunityCommentResponse> delete(@PathVariable Long commentId) {
         return ApiResponse.ok(adminCommunityService.deleteComment(commentId));

src/main/java/com/bop/youthpick/admin/board/controller/AdminCommunityPostController.java

@@ -5,6 +5,8 @@
 import com.bop.youthpick.admin.board.dto.AdminCommunityPostResponse;
 import com.bop.youthpick.admin.board.service.AdminCommunityService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.constraints.Pattern;
 import java.time.LocalDate;
 import java.util.List;
@@ -21,6 +23,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 커뮤니티 게시글")
 @RestController
 @RequestMapping("/api/v1/admin/community-posts")
 @RequiredArgsConstructor
@@ -29,6 +32,9 @@ public class AdminCommunityPostController {
 
     private final AdminCommunityService adminCommunityService;
 
+    @Operation(
+            summary = "커뮤니티 게시글 목록 조회",
+            description = "카테고리, 작성자, 작성일 범위로 커뮤니티 게시글을 검색해 페이지 단위로 조회합니다.")
     @GetMapping
     public ApiResponse<List<AdminCommunityPostResponse>> list(
             @RequestParam(required = false)
@@ -47,16 +53,19 @@ public ApiResponse<List<AdminCommunityPostResponse>> list(
         return ApiResponse.ok(page.getContent(), page);
     }
 
+    @Operation(summary = "게시글 댓글 목록 조회", description = "지정한 게시글에 달린 댓글 목록을 조회합니다.")
     @GetMapping("/{postId}/comments")
     public ApiResponse<List<AdminCommunityCommentResponse>> getComments(@PathVariable Long postId) {
         return ApiResponse.ok(adminCommunityService.getComments(postId));
     }
 
+    @Operation(summary = "게시글 첨부파일 목록 조회", description = "지정한 게시글에 첨부된 파일 목록을 조회합니다.")
     @GetMapping("/{postId}/attachments")
     public ApiResponse<List<AdminAttachmentResponse>> getAttachments(@PathVariable Long postId) {
         return ApiResponse.ok(adminCommunityService.getAttachments(postId));
     }
 
+    @Operation(summary = "커뮤니티 게시글 삭제", description = "관리자가 커뮤니티 게시글을 삭제합니다.")
     @DeleteMapping("/{postId}")
     public ApiResponse<AdminCommunityPostResponse> delete(@PathVariable Long postId) {
         return ApiResponse.ok(adminCommunityService.deletePost(postId));

src/main/java/com/bop/youthpick/admin/log/controller/AdminAppLogController.java

@@ -3,6 +3,8 @@
 import com.bop.youthpick.admin.log.dto.ApplicationLogResponse;
 import com.bop.youthpick.admin.log.service.AdminAppLogService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.constraints.Pattern;
 import java.time.LocalDate;
 import java.util.List;
@@ -17,6 +19,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 애플리케이션 로그")
 @RestController
 @RequestMapping("/api/v1/admin/application-logs")
 @RequiredArgsConstructor
@@ -25,6 +28,9 @@ public class AdminAppLogController {
 
     private final AdminAppLogService adminAppLogService;
 
+    @Operation(
+            summary = "애플리케이션 로그 목록 조회",
+            description = "로그 레벨, 키워드, 기간으로 애플리케이션 로그를 검색해 페이지 단위로 조회합니다.")
     @GetMapping
     public ApiResponse<List<ApplicationLogResponse>> list(
             @RequestParam(required = false)

src/main/java/com/bop/youthpick/admin/log/controller/AdminSearchLogController.java

@@ -3,6 +3,8 @@
 import com.bop.youthpick.admin.log.dto.SearchLogResponse;
 import com.bop.youthpick.admin.log.service.AdminSearchLogService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.time.LocalDate;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
@@ -15,13 +17,15 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 검색 로그")
 @RestController
 @RequestMapping("/api/v1/admin/search-logs")
 @RequiredArgsConstructor
 public class AdminSearchLogController {
 
     private final AdminSearchLogService adminSearchLogService;
 
+    @Operation(summary = "검색 로그 목록 조회", description = "키워드와 기간으로 검색 로그를 조회해 페이지 단위로 조회합니다.")
     @GetMapping
     public ApiResponse<List<SearchLogResponse>> list(
             @RequestParam(required = false) String keyword,

src/main/java/com/bop/youthpick/admin/policy/controller/AdminPolicyApplicationController.java

@@ -5,6 +5,8 @@
 import com.bop.youthpick.admin.policy.dto.ApplicationChecklistItemResponse;
 import com.bop.youthpick.admin.policy.service.AdminPolicyApplicationService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Pattern;
 import java.time.LocalDate;
@@ -23,6 +25,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 정책 신청관리")
 @RestController
 @RequestMapping("/api/v1/admin/policy-applications")
 @RequiredArgsConstructor
@@ -31,6 +34,9 @@ public class AdminPolicyApplicationController {
 
     private final AdminPolicyApplicationService adminPolicyApplicationService;
 
+    @Operation(
+            summary = "정책 신청 목록 조회",
+            description = "사용자, 정책명, 상태, 마감일 범위로 정책 신청 목록을 검색하여 페이지 단위로 조회한다.")
     @GetMapping
     public ApiResponse<List<AdminPolicyApplicationResponse>> list(
             @RequestParam(required = false) Long userId,
@@ -51,12 +57,14 @@ public ApiResponse<List<AdminPolicyApplicationResponse>> list(
         return ApiResponse.ok(page.getContent(), page);
     }
 
+    @Operation(summary = "신청 체크리스트 조회", description = "특정 정책 신청 건의 체크리스트 항목 목록을 조회한다.")
     @GetMapping("/{applicationId}/checklist")
     public ApiResponse<List<ApplicationChecklistItemResponse>> getChecklist(
             @PathVariable Long applicationId) {
         return ApiResponse.ok(adminPolicyApplicationService.getChecklist(applicationId));
     }
 
+    @Operation(summary = "신청 상태 변경", description = "특정 정책 신청 건의 상태를 변경한다.")
     @PatchMapping("/{applicationId}/status")
     public ApiResponse<AdminPolicyApplicationResponse> updateStatus(
             @PathVariable Long applicationId,

src/main/java/com/bop/youthpick/admin/policy/controller/AdminPolicyController.java

@@ -5,6 +5,8 @@
 import com.bop.youthpick.admin.policy.dto.AdminPolicyVisibilityUpdateRequest;
 import com.bop.youthpick.admin.policy.service.AdminPolicyService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Pattern;
 import java.time.LocalDate;
@@ -25,6 +27,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 정책")
 @RestController
 @RequestMapping("/api/v1/admin/policies")
 @RequiredArgsConstructor
@@ -33,6 +36,7 @@ public class AdminPolicyController {
 
     private final AdminPolicyService adminPolicyService;
 
+    @Operation(summary = "정책 목록 조회", description = "카테고리, 노출 상태, 기간으로 정책 목록을 검색하여 페이지 단위로 조회한다.")
     @GetMapping
     public ApiResponse<List<AdminPolicyResponse>> list(
             @RequestParam(required = false) String category,
@@ -51,12 +55,14 @@ public ApiResponse<List<AdminPolicyResponse>> list(
         return ApiResponse.ok(page.getContent(), page);
     }
 
+    @Operation(summary = "정책 정보 수정", description = "특정 정책의 정보를 수정한다.")
     @PutMapping("/{policyId}")
     public ApiResponse<AdminPolicyResponse> update(
             @PathVariable Long policyId, @Valid @RequestBody AdminPolicyUpdateRequest request) {
         return ApiResponse.ok(adminPolicyService.update(policyId, request));
     }
 
+    @Operation(summary = "정책 노출 상태 변경", description = "특정 정책의 노출 상태(VISIBLE/HIDDEN)를 변경한다.")
     @PatchMapping("/{policyId}/visibility")
     public ApiResponse<AdminPolicyResponse> updateVisibility(
             @PathVariable Long policyId,
@@ -65,6 +71,7 @@ public ApiResponse<AdminPolicyResponse> updateVisibility(
                 adminPolicyService.updateVisibility(policyId, request.visibilityStatus()));
     }
 
+    @Operation(summary = "정책 삭제", description = "특정 정책을 소프트 삭제 처리한다.")
     @DeleteMapping("/{policyId}")
     public ApiResponse<AdminPolicyResponse> delete(@PathVariable Long policyId) {
         return ApiResponse.ok(adminPolicyService.softDelete(policyId));

src/main/java/com/bop/youthpick/admin/policy/controller/AdminRegionController.java

@@ -3,19 +3,23 @@
 import com.bop.youthpick.admin.policy.service.AdminRegionService;
 import com.bop.youthpick.global.common.ApiResponse;
 import com.bop.youthpick.policy.dto.RegionResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 지역")
 @RestController
 @RequestMapping("/api/v1/admin/regions")
 @RequiredArgsConstructor
 public class AdminRegionController {
 
     private final AdminRegionService adminRegionService;
 
+    @Operation(summary = "지역 목록 조회", description = "전체 지역 목록을 조회한다.")
     @GetMapping
     public ApiResponse<List<RegionResponse>> list() {
         return ApiResponse.ok(adminRegionService.findAll());

src/main/java/com/bop/youthpick/admin/sync/controller/AdminBatchJobLogController.java

@@ -3,6 +3,8 @@
 import com.bop.youthpick.admin.sync.dto.BatchJobLogResponse;
 import com.bop.youthpick.admin.sync.service.AdminBatchJobLogService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.constraints.Pattern;
 import java.time.LocalDate;
 import java.util.List;
@@ -17,6 +19,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 배치 작업 이력")
 @RestController
 @RequestMapping("/api/v1/admin/batch-job-logs")
 @RequiredArgsConstructor
@@ -25,6 +28,7 @@ public class AdminBatchJobLogController {
 
     private final AdminBatchJobLogService adminBatchJobLogService;
 
+    @Operation(summary = "배치 작업 이력 조회", description = "상태, 기간으로 배치 작업 이력 목록을 검색하여 페이지 단위로 조회한다.")
     @GetMapping
     public ApiResponse<List<BatchJobLogResponse>> list(
             @RequestParam(required = false)

src/main/java/com/bop/youthpick/admin/sync/controller/AdminPolicySyncController.java

@@ -2,12 +2,15 @@
 
 import com.bop.youthpick.global.common.ApiResponse;
 import com.bop.youthpick.sync.service.PolicySyncService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 정책 동기화")
 @RestController
 @RequestMapping("/api/v1/admin/batch/policy-sync")
 @RequiredArgsConstructor
@@ -19,6 +22,11 @@ public class AdminPolicySyncController {
      * 정책 수집을 비동기로 시작시키고 즉시 202를 반환한다. 이미 실행 중이면 {@code SY001} 409 (GlobalExceptionHandler 변환). 결과
      * 확인은 {@code GET /api/v1/admin/batch-job-logs}(#57)로 한다.
      */
+    @Operation(
+            summary = "정책 동기화 트리거",
+            description =
+                    "정책 수집을 비동기로 시작시키고 즉시 202를 반환한다. 이미 실행 중이면 SY001 409(GlobalExceptionHandler 변환). 결과 확인은 GET"
+                            + " /api/v1/admin/batch-job-logs로 한다.")
     @PostMapping
     public ResponseEntity<ApiResponse<Void>> trigger() {
         policySyncService.startFullSyncAsync();

src/main/java/com/bop/youthpick/admin/sync/controller/AdminPolicySyncJobController.java

@@ -3,18 +3,22 @@
 import com.bop.youthpick.admin.sync.dto.PolicySyncJobSummaryResponse;
 import com.bop.youthpick.admin.sync.service.AdminPolicySyncJobService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 정책 동기화 작업")
 @RestController
 @RequestMapping("/api/v1/admin/policy-sync-jobs")
 @RequiredArgsConstructor
 public class AdminPolicySyncJobController {
 
     private final AdminPolicySyncJobService adminPolicySyncJobService;
 
+    @Operation(summary = "정책 동기화 작업 요약 조회", description = "정책 동기화 작업의 현황 요약 정보를 조회한다.")
     @GetMapping("/summary")
     public ApiResponse<PolicySyncJobSummaryResponse> summary() {
         return ApiResponse.ok(adminPolicySyncJobService.getSummary());

src/main/java/com/bop/youthpick/admin/user/controller/AdminLoginHistoryController.java

@@ -3,6 +3,8 @@
 import com.bop.youthpick.admin.user.dto.LoginHistoryResponse;
 import com.bop.youthpick.admin.user.service.AdminLoginHistoryService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.time.LocalDate;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
@@ -15,13 +17,15 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 로그인 이력")
 @RestController
 @RequestMapping("/api/v1/admin/login-histories")
 @RequiredArgsConstructor
 public class AdminLoginHistoryController {
 
     private final AdminLoginHistoryService adminLoginHistoryService;
 
+    @Operation(summary = "로그인 이력 목록 조회", description = "회원과 기간으로 로그인 이력을 검색해 페이지 단위로 조회합니다.")
     @GetMapping
     public ApiResponse<List<LoginHistoryResponse>> list(
             @RequestParam(required = false) Long userId,

src/main/java/com/bop/youthpick/admin/user/controller/AdminUserController.java

@@ -5,6 +5,8 @@
 import com.bop.youthpick.admin.user.dto.AdminUserRoleUpdateRequest;
 import com.bop.youthpick.admin.user.service.AdminUserService;
 import com.bop.youthpick.global.common.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Pattern;
 import java.util.List;
@@ -22,6 +24,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "관리자 - 회원")
 @RestController
 @RequestMapping("/api/v1/admin/users")
 @RequiredArgsConstructor
@@ -30,6 +33,7 @@ public class AdminUserController {
 
     private final AdminUserService adminUserService;
 
+    @Operation(summary = "회원 목록 조회", description = "권한, 계정 상태, 가입 경로로 회원을 검색해 페이지 단위로 조회합니다.")
     @GetMapping
     public ApiResponse<List<AdminUserResponse>> list(
             @RequestParam(required = false)
@@ -47,17 +51,20 @@ public ApiResponse<List<AdminUserResponse>> list(
         return ApiResponse.ok(page.getContent(), page);
     }
 
+    @Operation(summary = "회원 프로필 조회", description = "지정한 회원의 상세 프로필을 조회합니다.")
     @GetMapping("/{userId}/profile")
     public ApiResponse<AdminUserProfileResponse> getProfile(@PathVariable Long userId) {
         return ApiResponse.ok(adminUserService.getProfile(userId));
     }
 
+    @Operation(summary = "회원 권한 변경", description = "관리자가 지정한 회원의 권한(role)을 변경합니다.")
     @PatchMapping("/{userId}/role")
     public ApiResponse<AdminUserResponse> updateRole(
             @PathVariable Long userId, @Valid @RequestBody AdminUserRoleUpdateRequest request) {
         return ApiResponse.ok(adminUserService.updateRole(userId, request.role()));
     }
 
+    @Operation(summary = "회원 강제 탈퇴", description = "관리자가 지정한 회원을 소프트 삭제(강제 탈퇴) 처리합니다.")
     @DeleteMapping("/{userId}")
     public ApiResponse<AdminUserResponse> delete(@PathVariable Long userId) {
         return ApiResponse.ok(adminUserService.softDelete(userId));