Merge pull request #244 from 100-hours-a-week/feat-swagger

add: Swagger 기능 추가 및 컨트롤러 태그 업데이트

build.gradle

@@ -92,6 +92,9 @@ dependencies {
     //Bucket4j
     implementation 'com.bucket4j:bucket4j-redis:8.7.0'
 
+    //Swagger
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
+
 }
 
 tasks.named('bootBuildImage') {

src/main/java/connectripbe/connectrip_be/accompany/comment/web/AccompanyCommentController.java

@@ -3,6 +3,7 @@
 import connectripbe.connectrip_be.accompany.comment.dto.AccompanyCommentRequest;
 import connectripbe.connectrip_be.accompany.comment.dto.AccompanyCommentResponse;
 import connectripbe.connectrip_be.accompany.comment.service.AccompanyCommentService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
@@ -20,6 +21,7 @@
 @RestController
 @RequestMapping("api/v1/comment")
 @RequiredArgsConstructor
+@Tag(name = "Accompany Comment", description = "Accompany 게시물의 댓글 관리")
 public class AccompanyCommentController {
 
     private final AccompanyCommentService accompanyCommentService;

src/main/java/connectripbe/connectrip_be/accompany/post/web/AccompanyPostController.java

@@ -8,6 +8,7 @@
 import connectripbe.connectrip_be.accompany.post.exception.DuplicatedCustomUrlException;
 import connectripbe.connectrip_be.accompany.post.service.AccompanyPostService;
 import connectripbe.connectrip_be.global.dto.GlobalResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -24,6 +25,7 @@
 @RestController
 @RequestMapping("/api/v1/accompany/posts")
 @RequiredArgsConstructor
+@Tag(name = "Accompany Post", description = "Accompany 게시물 관리")
 public class AccompanyPostController {
 
     private final AccompanyPostService accompanyPostService;

src/main/java/connectripbe/connectrip_be/accompany/status/web/AccompanyStatusController.java

@@ -2,6 +2,7 @@
 
 import connectripbe.connectrip_be.accompany.status.response.AccompanyStatusResponse;
 import connectripbe.connectrip_be.accompany.status.service.AccompanyStatusServiceImpl;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -16,6 +17,7 @@
 @RestController
 @RequestMapping("/api/v1/accompany/posts")
 @RequiredArgsConstructor
+@Tag(name = "Accompany Status", description = "Accompany 게시물 상태 관리")
 public class AccompanyStatusController {
 
     private final AccompanyStatusServiceImpl accompanyStatusServiceImpl;

src/main/java/connectripbe/connectrip_be/auth/web/AuthController.java

@@ -7,6 +7,7 @@
 import connectripbe.connectrip_be.auth.kakao.service.KakaoService;
 import connectripbe.connectrip_be.auth.service.AuthService;
 import connectripbe.connectrip_be.global.dto.GlobalResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.Cookie;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
@@ -27,6 +28,7 @@
 @RestController
 @RequestMapping("/api/v1/auth")
 @RequiredArgsConstructor
+@Tag(name = "Auth", description = "인증 및 인가 관리")
 public class AuthController {
 
     private final AuthService authService;

src/main/java/connectripbe/connectrip_be/chat/web/ChatMessageController.java

@@ -3,6 +3,7 @@
 import connectripbe.connectrip_be.chat.dto.ChatMessageRequest;
 import connectripbe.connectrip_be.chat.dto.ChatMessageResponse;
 import connectripbe.connectrip_be.chat.service.ChatMessageService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.security.Principal;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
@@ -20,6 +21,7 @@
 
 @RestController
 @RequiredArgsConstructor
+@Tag(name = "Chat Message", description = "채팅 메시지 관리")
 public class ChatMessageController {
 
     private final ChatMessageService chatMessageService;

src/main/java/connectripbe/connectrip_be/chat/web/ChatRoomController.java

@@ -5,6 +5,7 @@
 import connectripbe.connectrip_be.chat.dto.ChatUnreadMessagesResponse;
 import connectripbe.connectrip_be.chat.service.ChatRoomService;
 import connectripbe.connectrip_be.global.dto.GlobalResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
@@ -18,6 +19,7 @@
 @RestController
 @RequestMapping("/api/v1/chatRoom")
 @RequiredArgsConstructor
+@Tag(name = "Chat Room", description = "채팅방 관리")
 public class ChatRoomController {
 
     private final ChatRoomService chatRoomService;

src/main/java/connectripbe/connectrip_be/chat/web/ChatRoomLocationController.java

@@ -3,6 +3,7 @@
 import connectripbe.connectrip_be.chat.dto.SearchChatRoomWithToggleResponse;
 import connectripbe.connectrip_be.chat.dto.UpdateChatRoomSharingRequest;
 import connectripbe.connectrip_be.chat.service.ChatRoomLocationService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -18,6 +19,7 @@
 @RestController
 @RequestMapping("/api/v1/chatRoom")
 @RequiredArgsConstructor
+@Tag(name = "Chat Room Location", description = "채팅방 위치 공유 관리")
 public class ChatRoomLocationController {
 
     private final ChatRoomLocationService chatRoomLocationService;

src/main/java/connectripbe/connectrip_be/community/comment/web/CommunityCommentController.java

@@ -3,6 +3,7 @@
 import connectripbe.connectrip_be.community.comment.dto.CommunityCommentRequest;
 import connectripbe.connectrip_be.community.comment.dto.CommunityCommentResponse;
 import connectripbe.connectrip_be.community.comment.service.CommunityCommentService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
@@ -19,6 +20,7 @@
 @RestController
 @RequestMapping("api/v1/community/comment")
 @RequiredArgsConstructor
+@Tag(name = "Community Comment", description = "커뮤니티 댓글 관리")
 public class CommunityCommentController {
 
     private final CommunityCommentService communityCommentService;

src/main/java/connectripbe/connectrip_be/community/post/web/CommunityPostController.java

@@ -5,6 +5,7 @@
 import connectripbe.connectrip_be.community.post.dto.SearchCommunityPostSummaryResponse;
 import connectripbe.connectrip_be.community.post.dto.UpdateCommunityPostRequest;
 import connectripbe.connectrip_be.community.post.service.CommunityPostService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -20,6 +21,7 @@
 @RestController
 @RequestMapping("/api/v1/community/posts")
 @RequiredArgsConstructor
+@Tag(name = "Community Post", description = "커뮤니티 게시물 관리")
 public class CommunityPostController {
 
     private final CommunityPostService communityPostService;

src/main/java/connectripbe/connectrip_be/global/config/SwaggerConfig.java

@@ -0,0 +1,44 @@
+package connectripbe.connectrip_be.global.config;
+
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@OpenAPIDefinition(
+        info = @Info(
+                title = "Example API Docs",
+                description = "Description",
+                version = "v1"
+        )
+)
+@Configuration
+public class SwaggerConfig {
+
+    @Bean
+    public OpenAPI openAPI() {
+        String securityJwtName = "JWT";
+
+        // 쿠키 기반 보안 요구 사항 설정
+        SecurityRequirement securityRequirement = new SecurityRequirement().addList(securityJwtName);
+
+        // 쿠키 기반 SecurityScheme 설정
+        Components components = new Components()
+                .addSecuritySchemes(securityJwtName, new SecurityScheme()
+                        .name(securityJwtName)
+                        .type(SecurityScheme.Type.APIKEY)
+                        .in(SecurityScheme.In.COOKIE) // 쿠키를 통해 인증
+                        .bearerFormat(securityJwtName) // JWT 형식
+                        .scheme("cookie"));
+
+        // OpenAPI 반환: 보안 요구 사항 및 보안 스키마를 포함
+        return new OpenAPI()
+                .addSecurityItem(securityRequirement)
+                .components(components);
+    }
+}
+

src/main/java/connectripbe/connectrip_be/health_check/web/HealthCheckController.java

@@ -1,12 +1,14 @@
 package connectripbe.connectrip_be.health_check.web;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 @RestController
 @RequestMapping("/api/v1/health-check")
+@Tag(name = "Health Check", description = "애플리케이션 상태 확인")
 public class HealthCheckController {
 
     @GetMapping

src/main/java/connectripbe/connectrip_be/member/web/MemberController.java

@@ -10,6 +10,7 @@
 import connectripbe.connectrip_be.member.dto.ProfileUpdateRequestDto;
 import connectripbe.connectrip_be.member.dto.TokenAndHeaderInfoDto;
 import connectripbe.connectrip_be.member.service.MemberService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.Cookie;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
@@ -28,6 +29,7 @@
 @RestController
 @RequestMapping("/api/v1/members")
 @RequiredArgsConstructor
+@Tag(name = "Member", description = "회원 정보 관리")
 public class MemberController {
 
     private final MemberService memberService;

src/main/java/connectripbe/connectrip_be/notification/web/NotificationController.java

@@ -1,6 +1,7 @@
 package connectripbe.connectrip_be.notification.web;
 
 import connectripbe.connectrip_be.notification.service.NotificationService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
@@ -15,6 +16,7 @@
 @RestController
 @RequestMapping("/api/v1/notifications")
 @RequiredArgsConstructor
+@Tag(name = "Pending List", description = "Accompany 게시물의 대기자 목록 관리")
 public class NotificationController {
 
     private final NotificationService notificationService;

src/main/java/connectripbe/connectrip_be/review/web/AccompanyReviewController.java

@@ -5,6 +5,7 @@
 import connectripbe.connectrip_be.review.dto.response.AccompanyReviewResponse;
 import connectripbe.connectrip_be.review.dto.response.AccompanyReviewSummaryResponse;
 import connectripbe.connectrip_be.review.service.AccompanyReviewService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -19,6 +20,7 @@
 @RestController
 @RequestMapping("/api/v1/reviews")
 @RequiredArgsConstructor
+@Tag(name = "Accompany Review", description = "Accompany 리뷰 관리")
 public class AccompanyReviewController {
 
     private final AccompanyReviewService accompanyReviewService;

src/main/resources/application.yml

@@ -26,3 +26,22 @@ cloud:
       auto: false
     stack:
       auto: false
+
+springdoc:
+  swagger-ui:
+    groups-order: DESC
+    tags-sorter: alpha
+    operations-sorter: method
+    disable-swagger-default-url: true
+    display-request-duration: true
+    defaultModelsExpandDepth: 2
+    defaultModelExpandDepth: 2
+  api-docs:
+    path: /api-docs
+  show-actuator: true
+  default-consumes-media-type: application/json
+  default-produces-media-type: application/json
+  writer-with-default-pretty-printer: true
+  model-and-view-allowed: true
+  paths-to-match:
+    - /api/v1/**