refactor: Swagger 스펙을 ControllerDocs 인터페이스로 분리

src/main/java/ssu/eatssu/domain/auth/presentation/OAuthController.java

@@ -1,11 +1,5 @@
 package ssu.eatssu.domain.auth.presentation;
 
-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.responses.ApiResponses;
-import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -14,6 +8,7 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 import ssu.eatssu.domain.auth.dto.*;
+import ssu.eatssu.domain.auth.presentation.docs.OAuthControllerDocs;
 import ssu.eatssu.domain.auth.service.OAuthService;
 import ssu.eatssu.domain.user.dto.Tokens;
 import ssu.eatssu.global.handler.response.BaseResponse;
@@ -24,19 +19,12 @@
 @RestController
 @RequestMapping("/oauths")
 @RequiredArgsConstructor
-@Tag(name = "Oauth", description = "Oauth API")
-public class OAuthController {
+public class OAuthController implements OAuthControllerDocs {
 
     private final OAuthService oauthService;
 
     // TODO : 로그인 & 회원 가입 마이그레이션 이후에 지울 것.
-    @Operation(summary = "카카오 회원가입, 로그인 [인증 토큰 필요 X]", description = """
-            카카오 회원가입, 로그인 API 입니다.<br><br>
-            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
-            """)
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "카카오 회원가입/로그인 성공")
-    })
+    @Override
     @PostMapping("/kakao")
     public BaseResponse<Tokens> kakaoLogin(@Valid @RequestBody KakaoLoginRequest request) {
         long startTime = System.currentTimeMillis();
@@ -48,13 +36,7 @@ public BaseResponse<Tokens> kakaoLogin(@Valid @RequestBody KakaoLoginRequest req
         return BaseResponse.success(tokens);
     }
 
-    @Operation(summary = "카카오 회원가입, 로그인 V2 [인증 토큰 필요 X]", description = """
-            카카오 회원가입, 로그인 V2 API 입니다.<br><br>
-            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
-            """)
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "카카오 회원가입/로그인 성공")
-    })
+    @Override
     @PostMapping("/v2/kakao")
     public BaseResponse<Tokens> kakaoLoginV2(@Valid @RequestBody KakaoLoginRequestV2 request) {
         long startTime = System.currentTimeMillis();
@@ -67,46 +49,28 @@ public BaseResponse<Tokens> kakaoLoginV2(@Valid @RequestBody KakaoLoginRequestV2
     }
 
     // TODO : 로그인 & 회원 가입 마이그레이션 이후에 지울 것.
-    @Operation(summary = "애플 회원가입, 로그인 [인증 토큰 필요 X]", description = """
-            애플 로그인, 회원가입 API 입니다.<br><br>
-            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
-            """)
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "애플 회원가입/로그인 성공")
-    })
+    @Override
     @PostMapping("/apple")
     public BaseResponse<Tokens> appleLogin(@Valid @RequestBody AppleLoginRequest request) {
         Tokens tokens = oauthService.appleLogin(request);
         return BaseResponse.success(tokens);
     }
 
-    @Operation(summary = "애플 회원가입, 로그인 V2 [인증 토큰 필요 X]", description = """
-            애플 로그인, 회원가입 API V2 입니다.<br><br>
-            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
-            """)
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "애플 회원가입/로그인 성공")
-    })
+    @Override
     @PostMapping("/v2/apple")
     public BaseResponse<Tokens> appleLoginV2(@Valid @RequestBody AppleLoginRequestV2 request) {
         Tokens tokens = oauthService.appleLoginV2(request);
         return BaseResponse.success(tokens);
     }
 
-    @Operation(summary = "토큰 재발급", description = "accessToken, refreshToken 재발급 API 입니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "토큰 재발급 성공")
-    })
+    @Override
     @PostMapping("/reissue/token")
     public BaseResponse<Tokens> refreshToken() {
         Tokens tokens = oauthService.refreshTokens(getLoginUser());
         return BaseResponse.success(tokens);
     }
 
-    @Operation(summary = "유효한 토큰 확인 [인증 토큰 필요 X]", description = "해당 토큰이 유효하면 true 반환하는, 유효하지 않은 false 반환하는 API 입니다")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "유효한 토큰인지 확인 성공")
-    })
+    @Override
     @PostMapping("/valid/token")
     public BaseResponse<Boolean> validToken(@Valid @RequestBody ValidRequest request) {
         Boolean response = oauthService.validToken(request);

src/main/java/ssu/eatssu/domain/auth/presentation/docs/OAuthControllerDocs.java

@@ -0,0 +1,65 @@
+package ssu.eatssu.domain.auth.presentation.docs;
+
+import io.swagger.v3.oas.annotations.Operation;
+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 ssu.eatssu.domain.auth.dto.AppleLoginRequest;
+import ssu.eatssu.domain.auth.dto.AppleLoginRequestV2;
+import ssu.eatssu.domain.auth.dto.KakaoLoginRequest;
+import ssu.eatssu.domain.auth.dto.KakaoLoginRequestV2;
+import ssu.eatssu.domain.auth.dto.ValidRequest;
+import ssu.eatssu.domain.user.dto.Tokens;
+import ssu.eatssu.global.handler.response.BaseResponse;
+
+@Tag(name = "Oauth", description = "Oauth API")
+public interface OAuthControllerDocs {
+
+    @Operation(summary = "카카오 회원가입, 로그인 [인증 토큰 필요 X]", description = """
+            카카오 회원가입, 로그인 API 입니다.<br><br>
+            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
+            """)
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "카카오 회원가입/로그인 성공")
+    })
+    BaseResponse<Tokens> kakaoLogin(KakaoLoginRequest request);
+
+    @Operation(summary = "카카오 회원가입, 로그인 V2 [인증 토큰 필요 X]", description = """
+            카카오 회원가입, 로그인 V2 API 입니다.<br><br>
+            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
+            """)
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "카카오 회원가입/로그인 성공")
+    })
+    BaseResponse<Tokens> kakaoLoginV2(KakaoLoginRequestV2 request);
+
+    @Operation(summary = "애플 회원가입, 로그인 [인증 토큰 필요 X]", description = """
+            애플 로그인, 회원가입 API 입니다.<br><br>
+            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
+            """)
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "애플 회원가입/로그인 성공")
+    })
+    BaseResponse<Tokens> appleLogin(AppleLoginRequest request);
+
+    @Operation(summary = "애플 회원가입, 로그인 V2 [인증 토큰 필요 X]", description = """
+            애플 로그인, 회원가입 API V2 입니다.<br><br>
+            가입된 회원일 경우 카카오 로그인, 미가입 회원일 경우 회원가입 후 자동 로그인됩니다.
+            """)
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "애플 회원가입/로그인 성공")
+    })
+    BaseResponse<Tokens> appleLoginV2(AppleLoginRequestV2 request);
+
+    @Operation(summary = "토큰 재발급", description = "accessToken, refreshToken 재발급 API 입니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "토큰 재발급 성공")
+    })
+    BaseResponse<Tokens> refreshToken();
+
+    @Operation(summary = "유효한 토큰 확인 [인증 토큰 필요 X]", description = "해당 토큰이 유효하면 true 반환하는, 유효하지 않은 false 반환하는 API 입니다")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "유효한 토큰인지 확인 성공")
+    })
+    BaseResponse<Boolean> validToken(ValidRequest request);
+}

src/main/java/ssu/eatssu/domain/inquiry/presentation/InquiryController.java

@@ -1,11 +1,5 @@
 package ssu.eatssu.domain.inquiry.presentation;
 
-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.responses.ApiResponses;
-import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -15,6 +9,7 @@
 import ssu.eatssu.domain.auth.security.CustomUserDetails;
 import ssu.eatssu.domain.inquiry.dto.CreateInquiryRequest;
 import ssu.eatssu.domain.inquiry.entity.Inquiry;
+import ssu.eatssu.domain.inquiry.presentation.docs.InquiryControllerDocs;
 import ssu.eatssu.domain.inquiry.service.InquiryService;
 import ssu.eatssu.domain.slack.entity.SlackChannel;
 import ssu.eatssu.domain.slack.entity.SlackMessageFormat;
@@ -28,17 +23,12 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/inquiries")
-@Tag(name = "Inquiry", description = "문의 API")
-public class InquiryController {
+public class InquiryController implements InquiryControllerDocs {
 
     private final SlackService slackService;
     private final InquiryService inquiryService;
 
-    @Operation(summary = "문의 작성", description = "문의를 작성하는 API 입니다.")
-    @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "문의 작성 성공"),
-            @ApiResponse(responseCode = "404", description = "존재하지 않는 유저", content = @Content(schema = @Schema(implementation = BaseResponse.class)))
-    })
+    @Override
     @PostMapping("/")
     public BaseResponse<Void> writeInquiry(@RequestBody CreateInquiryRequest createInquiryRequest,
                                            @AuthenticationPrincipal CustomUserDetails customUserDetails) {

src/main/java/ssu/eatssu/domain/inquiry/presentation/docs/InquiryControllerDocs.java

@@ -0,0 +1,24 @@
+package ssu.eatssu.domain.inquiry.presentation.docs;
+
+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.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import ssu.eatssu.domain.auth.security.CustomUserDetails;
+import ssu.eatssu.domain.inquiry.dto.CreateInquiryRequest;
+import ssu.eatssu.global.handler.response.BaseResponse;
+
+@Tag(name = "Inquiry", description = "문의 API")
+public interface InquiryControllerDocs {
+
+    @Operation(summary = "문의 작성", description = "문의를 작성하는 API 입니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "문의 작성 성공"),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 유저", content = @Content(schema =
+            @Schema(implementation = BaseResponse.class)))
+    })
+    BaseResponse<Void> writeInquiry(CreateInquiryRequest createInquiryRequest,
+                                    CustomUserDetails customUserDetails);
+}