[DOCUMENT] Swagger의 Controller, Method에 기록될 API설명 추가.

core/core-api/src/main/java/com/nerd/favorite18/core/api/auth/controller/AuthController.java

@@ -6,27 +6,32 @@
 import com.nerd.favorite18.core.api.auth.dto.request.AuthRefreshRequest;
 import com.nerd.favorite18.core.api.jwt.dto.JwtResponse;
 import com.nerd.favorite18.core.api.user.dto.UserDto;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "1.2 [토큰 재발급 및 로그아웃]", description = "사용자 토큰 재발급 및 로그아웃")
 @Slf4j
 @RequiredArgsConstructor
 @RequestMapping("/api/auth")
 @RestController
 public class AuthController {
     private final AuthBusiness authBusiness;
 
+    @Operation(summary = "토큰 재발급", description = "토큰 재발급을 요청하며, 성공시 새로운 토큰을 발급받는다.")
     @PostMapping("/refresh-token")
     public ApiResponse<JwtResponse> refreshToken(@RequestBody AuthRefreshRequest request) {
         final JwtResponse jwtResponse = authBusiness.refreshToken(request);
 
         return ApiResponse.success(jwtResponse);
     }
 
+    @Operation(summary = "로그아웃", description = "로그아웃을 요청하며, 성공시 세션에서 사용자 정보를 제거한다.")
     @PostMapping("/logout")
     public ApiResponse<Void> logout(@UserSession UserDto user) {
         authBusiness.logout(user);

core/core-api/src/main/java/com/nerd/favorite18/core/api/auth/controller/AuthOpenApiController.java

@@ -6,6 +6,8 @@
 import com.nerd.favorite18.core.api.auth.dto.request.AuthSignupGoogleRequest;
 import com.nerd.favorite18.core.api.jwt.dto.JwtResponse;
 import com.nerd.favorite18.core.api.user.dto.UserDto;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -17,6 +19,7 @@
 
 import java.net.URI;
 
+@Tag(name = "1.1 [회원가입 및 로그인]", description = "회원가입 및 사용자 토큰 발급")
 @Slf4j
 @RequiredArgsConstructor
 @RequestMapping("/open-api/auth")
@@ -25,6 +28,7 @@ public class AuthOpenApiController {
     private final AuthBusiness authBusiness;
 
     // 모바일 회원가입 진행
+    @Operation(summary = "회원가입", description = "회원가입을 진행하며, 성공시 사용자 정보를 반환한다.")
     @PostMapping("/signup")
     public ApiResponse<UserDto> signUp(@RequestBody AuthSignupGoogleRequest request) {
         final UserDto userDto = authBusiness.signUp(request);
@@ -33,6 +37,7 @@ public ApiResponse<UserDto> signUp(@RequestBody AuthSignupGoogleRequest request)
     }
 
     // 모바일 로그인 진행
+    @Operation(summary = "로그인", description = "로그인을 진행하며, 성공시 토큰을 반환한다.")
     @PostMapping("/login/google")
     public ApiResponse<JwtResponse> loginGoogle(@RequestBody AuthLoginGoogleRequest request) {
         final JwtResponse jwtResponse = authBusiness.loginGoogle(request);
@@ -41,13 +46,15 @@ public ApiResponse<JwtResponse> loginGoogle(@RequestBody AuthLoginGoogleRequest
     }
 
     // 로그인 url 발행 요청
+    @Operation(summary = "로그인", description = "로그인을 진행하며, 성공시 로그인 url을 반환한다.")
     @GetMapping("/login")
     public URI login() {
 
         return authBusiness.login();
     }
 
     // 웹 로그인 콜백 주소
+    @Operation(summary = "구글 로그인 콜백", description = "구글 로그인 콜백을 진행하며, 성공시 토큰을 반환한다.")
     @GetMapping("/login/oauth2/code/google")
     public ApiResponse<JwtResponse> callbackGoogle(@RequestParam("code") String authorizationCode) {
         final JwtResponse jwtResponse = authBusiness.callbackGoogle(authorizationCode);

core/core-api/src/main/java/com/nerd/favorite18/core/api/code/EnumController.java

@@ -5,6 +5,10 @@
 import com.nerd.favorite18.core.api._common.support.response.ApiResponse;
 import com.nerd.favorite18.core.enums.common.EnumMapper;
 import com.nerd.favorite18.core.enums.common.EnumMapperValue;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.List;
 import java.util.Map;
 import lombok.RequiredArgsConstructor;
@@ -14,6 +18,7 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "0.1 [공통코드, Enum]", description = "Enum 타입, 공통코드 정보")
 @Slf4j
 @RestController
 @RequestMapping("/enum")
@@ -22,13 +27,20 @@ public class EnumController {
 
     private final EnumMapper enumMapper;
 
+    @Operation(summary = "전체 Enum 정보 조회", description = "전체 Enum 정보를 조회한다.")
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "데이터 조회 성공")
     @GetMapping
     public ApiResponse<Map<String, List<EnumMapperValue>>> fetchAllEnumMap() {
         return ApiResponse.success(enumMapper.getAll());
     }
 
+    @Operation(summary = "Key를 가지고 있는 Enum 조회", description = "Enum의 클래스 명을 가지고 있는지 확인하고, 해당 Enum 정보를 조회한다.")
+    @ApiResponses(value = {
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "데이터 조회 성공"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "동일한 명칭의 TypeClass가 존재하지 않음")
+    })
     @GetMapping("/{key}")
-    public ApiResponse<List<EnumMapperValue>> fetchEnumListByKey(@PathVariable String key) {
+    public ApiResponse<List<EnumMapperValue>> fetchEnumListByKey(@Parameter(name = "TypeName") @PathVariable("key") String key) {
         if (!enumMapper.isContainsKey(key)) {
             throw new CoreApiException(ErrorType.BAD_REQUEST);
         }

core/core-api/src/main/java/com/nerd/favorite18/core/api/model/controller/ModelScoreController.java

@@ -11,6 +11,8 @@
 import com.nerd.favorite18.core.api.model.dto.response.ModelScoreResponse;
 import com.nerd.favorite18.core.api.model.dto.response.ModelUploadResponse;
 import com.nerd.favorite18.core.api.user.dto.UserDto;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -23,6 +25,7 @@
 
 import java.util.List;
 
+@Tag(name = "2.1 [모델 점수]", description = "모델 점수 분석")
 @Slf4j
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/model")
@@ -31,6 +34,7 @@ public class ModelScoreController {
     private final ModelScoreBusiness modelScoreBusiness;
 
     // 내 점수 분석 히스토리
+    @Operation(summary = "내 점수 분석 히스토리", description = "내 점수 분석 히스토리를 조회한다.")
     @GetMapping("/score")
     public ApiResponse<List<ModelScoreListResponse>> getMyScoreList(@UserSession UserDto userDto) {
         final List<ModelScoreListResponse> response = modelScoreBusiness.getMyScoreList(userDto);
@@ -39,6 +43,7 @@ public ApiResponse<List<ModelScoreListResponse>> getMyScoreList(@UserSession Use
     }
 
     // 녹음 파일 서버 업로드
+    @Operation(summary = "녹음 파일 서버 업로드", description = "녹음 파일을 서버에 업로드한다.")
     @PostMapping("/record")
     public ApiResponse<ModelUploadResponse> uploadFile(
             @UserSession UserDto userDto,
@@ -56,6 +61,7 @@ public ApiResponse<ModelUploadResponse> uploadFile(
     }
 
     // 녹음 파일 점수 분석
+    @Operation(summary = "녹음 파일 점수 분석", description = "녹음 파일을 분석하여 점수를 반환한다.")
     @PostMapping("/score")
     public ApiResponse<ModelScoreResponse> scoreModel(
             @RequestBody ModelScoreRequest request

core/core-api/src/main/java/com/nerd/favorite18/core/api/qna/controller/QnaAdminController.java

@@ -8,6 +8,8 @@
 import com.nerd.favorite18.core.api.qna.dto.response.QnaResponse;
 import com.nerd.favorite18.core.api.user.dto.UserDto;
 import com.nerd.favorite18.core.enums.qna.QnaProgressStatus;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
@@ -19,39 +21,43 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "3.2 [Q&A(관리자)]", description = "관리자만 사용가능한 Q&A API")
 @RequiredArgsConstructor
 @RequestMapping("/admin-api/v1/qna")
 @RestController
 public class QnaAdminController {
     private final QnaAdminBusiness qnaAdminBusiness;
 
+    @Operation(summary = "Q&A 목록 조회", description = "Q&A 목록을 조회한다.")
     @GetMapping
     public ApiResponse<Page<QnaResponse>> getQnas(
-            @UserSession UserDto userDto,
-            @RequestParam(required = false) QnaProgressStatus progressStatus,
-            Pageable pageable
+        @UserSession UserDto userDto,
+        @RequestParam(required = false) QnaProgressStatus progressStatus,
+        Pageable pageable
     ) {
         Page<QnaResponse> response = qnaAdminBusiness.getQnas(progressStatus, pageable);
 
         return ApiResponse.success(response);
     }
 
+    @Operation(summary = "내 Q&A 목록 조회", description = "내 Q&A 목록을 조회한다.")
     @GetMapping("/me")
     public ApiResponse<Page<QnaResponse>> getMyQnas(
-            @UserSession UserDto userDto,
-            @RequestParam(required = false) QnaProgressStatus progressStatus,
-            Pageable pageable
+        @UserSession UserDto userDto,
+        @RequestParam(required = false) QnaProgressStatus progressStatus,
+        Pageable pageable
     ) {
         Page<QnaResponse> response = qnaAdminBusiness.getMyQnas(userDto, progressStatus, pageable);
 
         return ApiResponse.success(response);
     }
 
+    @Operation(summary = "Q&A 정보 변경", description = "Q&A정보를 수정한다.")
     @PutMapping("/{id}")
     public ApiResponse<QnaDto> updateQna(
-            @UserSession UserDto userDto,
-            @PathVariable("id") Long qnaId,
-            @RequestBody QnaUpdateRequest request
+        @UserSession UserDto userDto,
+        @PathVariable("id") Long qnaId,
+        @RequestBody QnaUpdateRequest request
     ) {
         final QnaDto response = qnaAdminBusiness.updateQna(userDto, qnaId, request);
 

core/core-api/src/main/java/com/nerd/favorite18/core/api/qna/controller/QnaController.java

@@ -8,33 +8,39 @@
 import com.nerd.favorite18.core.api.user.dto.UserDto;
 import com.nerd.favorite18.storage.db.core.qna.entity.Qna;
 import com.nerd.favorite18.storage.db.core.qna.projection.QnaListResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "3.1 [Q&A(전체)]", description = "일반 사용자와 관리자 모두 사용가능한 Q&A API")
 @Slf4j
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/qna")
 @RestController
 public class QnaController {
     private final QnaBusiness qnaBusiness;
 
+    @Operation(summary = "내 Q&A 목록", description = "내 Q&A 목록을 조회한다.")
     @GetMapping
     public ApiResponse<Page<QnaListResponse>> getMyQnaList(@UserSession UserDto userDto, Pageable pageable) {
         Page<QnaListResponse> response = qnaBusiness.getMyQnaList(userDto, pageable);
 
         return ApiResponse.success(response);
     }
 
+    @Operation(summary = "Q&A 상세 조회", description = "Q&A 상세 정보를 조회한다.")
     @GetMapping("/{id}")
     public ApiResponse<QnaDto> getQna(@UserSession UserDto userDto, @PathVariable Long id) {
         QnaDto response = qnaBusiness.getQna(userDto, id);
 
         return ApiResponse.success(response);
     }
 
+    @Operation(summary = "Q&A 등록", description = "Q&A를 등록한다.")
     @PostMapping
     public ApiResponse<Qna> addQna(@UserSession UserDto userDto, @RequestBody QnaAddRequest request) {
         Qna response = qnaBusiness.addQna(userDto, request);

core/core-api/src/main/java/com/nerd/favorite18/core/api/ranking/controller/RankController.java

@@ -5,20 +5,24 @@
 import com.nerd.favorite18.core.api.ranking.dto.response.RankResponse;
 import com.nerd.favorite18.core.enums.song.MachineType;
 import com.nerd.favorite18.storage.db.core.ranking.projection.RankListProjection;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.*;
 
 import java.time.LocalDate;
 import java.util.List;
 
+@Tag(name = "4.1 [랭킹]", description = "랭킹 정보")
 @Slf4j
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/rank")
 @RestController
 public class RankController {
     private final RankBusiness rankBusiness;
 
+    @Operation(summary = "전체 랭킹 조회", description = "전체 랭킹 정보를 조회한다.")
     @GetMapping
     public ApiResponse<List<RankResponse>> getRankAll(@RequestParam LocalDate today, @RequestParam MachineType machineType) {
         List<RankResponse> response = rankBusiness.getRankAll(today, machineType);

core/core-api/src/main/java/com/nerd/favorite18/core/api/ranking/controller/RankRedisController.java

@@ -4,6 +4,8 @@
 import com.nerd.favorite18.core.api.ranking.business.RankRedisBusiness;
 import com.nerd.favorite18.core.api.ranking.business.RankRedisBusinessV2;
 import com.nerd.favorite18.core.api.ranking.dto.response.RankScoreResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -15,6 +17,7 @@
 
 import java.util.List;
 
+@Tag(name = "4.2 [랭킹(Redis)]", description = "랭킹 정보(Redis)")
 @Slf4j
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/rank/redis")
@@ -27,13 +30,15 @@ public class RankRedisController {
     /**
      * 1~100위 노래 ID 조회
      */
+    @Operation(summary = "1~100위 노래 ID 조회", description = "1~100위 노래 ID를 조회한다.")
     @GetMapping
     public List<RankScoreResponse> getTop100Songs() {
 
         return rankRedisBusinessV2.getTop100Songs();
     }
 
     /** 노래 상세정보 클릭 시 */
+    @Operation(summary = "노래 클릭", description = "노래 클릭 시 랭킹 정보를 업데이트한다.")
     @PostMapping("/{songId}")
     public ApiResponse<Void> clickSong(@PathVariable Long songId){
         rankRedisBusinessV2.clickSong(songId);
@@ -42,6 +47,7 @@ public ApiResponse<Void> clickSong(@PathVariable Long songId){
     }
 
     // 랭킹 키 삭제 API
+    @Operation(summary = "레디스 랭킹 키 삭제", description = "레디스에 저장된 노래 캐시와 카운트 리스트를 삭제")
     @DeleteMapping
     public ApiResponse<Void> deleteKeys() {
         rankRedisBusinessV2.deleteKeys();

core/core-api/src/main/java/com/nerd/favorite18/core/api/song/controller/SongAdminController.java

@@ -7,6 +7,8 @@
 import com.nerd.favorite18.core.api.song.dto.request.SongUpdateRequest;
 import com.nerd.favorite18.core.api.song.dto.response.SongResponse;
 import com.nerd.favorite18.core.api.user.dto.UserDto;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.data.domain.Page;
@@ -22,6 +24,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "4.3 [노래-관리자용]", description = "노래 정보")
 @Slf4j
 @RestController
 @RequiredArgsConstructor
@@ -30,6 +33,7 @@ public class SongAdminController {
     private final SongBusiness songBusiness;
 
     /** 노래 리스트 전체 조회 */
+    @Operation(summary = "노래 리스트 전체 조회", description = "노래 리스트 전체를 조회한다.")
     @GetMapping
     public ApiResponse<Page<SongResponse>> getSongs(
         @RequestParam(name = "keyword", required = false) String keyword,
@@ -39,13 +43,15 @@ public ApiResponse<Page<SongResponse>> getSongs(
     }
 
     /* 노래 단건 조회 **/
+    @Operation(summary = "노래 단건 조회", description = "노래 단건을 조회한다.")
     @GetMapping("/{id}")
     public ApiResponse<SongResponse> getSong(@PathVariable("id") Long songId) {
         return ApiResponse.success(songBusiness.getSong(songId));
     }
 
 
     /** 노래 수동 등록 */
+    @Operation(summary = "노래 수동 등록", description = "노래를 직접으로 등록한다.")
     @PostMapping
     public ApiResponse<SongResponse> createSong(
         @UserSession UserDto user,
@@ -56,6 +62,7 @@ public ApiResponse<SongResponse> createSong(
 
 
     /** 노래 정보 수정 */
+    @Operation(summary = "노래 정보 수정", description = "노래 정보를 수정한다.")
     @PutMapping
     public ApiResponse<Void> updateSong(
         @UserSession UserDto user,
@@ -66,6 +73,7 @@ public ApiResponse<Void> updateSong(
     }
 
     /** 노래 정보 삭제 */
+    @Operation(summary = "노래 정보 삭제", description = "노래 정보를 삭제한다.")
     @DeleteMapping("/{id}")
     public ApiResponse<Void> deleteSong(
         @UserSession UserDto user,