Merge pull request #125 from dnd-side-project/docs/#123

Add Skill API Documentation

src/main/java/com/dnd/spaced/domain/admin/presentation/SwaggerAdminController.java

@@ -1,12 +1,14 @@
 package com.dnd.spaced.domain.admin.presentation;
 
 import com.dnd.spaced.domain.admin.application.dto.request.AdminWordRequestDto;
+import com.dnd.spaced.domain.admin.presentation.dto.request.AdminMultipleWordConditionRequest;
 import com.dnd.spaced.domain.admin.presentation.dto.response.AdminWordResponse;
 import com.dnd.spaced.domain.admin.presentation.dto.response.ReportListResponse;
 import com.dnd.spaced.global.docs.annotation.ExceptionSpec;
 import com.dnd.spaced.global.docs.annotation.ExcludeCommonHeaderSpec;
 import com.dnd.spaced.global.docs.annotation.NotRequiredCommonHeaderSpec;
 import com.dnd.spaced.global.exception.ExceptionCode;
+import com.dnd.spaced.global.resolver.word.WordSortCondition;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.media.Content;
@@ -15,14 +17,25 @@
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
+import org.springframework.data.domain.Pageable;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestParam;
 
-@Tag(name = "관리자 관련 API", description = "용어 생성, 용어 삭제, 용어 수정, 신고 수락, 신고 무시, 신고 목록 조회")
+import java.util.List;
+
+@Tag(name = "관리자 관련 API", description = "용어 목록 조회, 용어 생성, 용어 삭제, 용어 수정, 신고 수락, 신고 무시, 신고 목록 조회")
 public interface SwaggerAdminController {
 
+    @ExcludeCommonHeaderSpec
+    @Operation(summary = "용어 목록 조회", description = "관리자가 용어 목록을 조회합니다.")
+    @ApiResponse(responseCode = "200", description = "OK")
+    ResponseEntity<List<AdminWordResponse>> findAllBy(
+            AdminMultipleWordConditionRequest request,
+            @WordSortCondition Pageable pageable
+    );
+
     @ExcludeCommonHeaderSpec
     @Operation(summary = "용어 등록", description = "관리자가 새로운 용어를 등록합니다.")
     @ApiResponse(responseCode = "201", description = "Created")

src/main/java/com/dnd/spaced/domain/admin/presentation/dto/response/AdminWordResponse.java

@@ -17,7 +17,11 @@ public record AdminWordResponse(
         @Schema(description = "뜻")
         String meaning,
 
-        @Schema(description = "카테고리")
+        @Schema(
+                description = "용어 카테고리",
+                allowableValues = {"전체", "디자인", "개발", "비즈니스"},
+                requiredMode = Schema.RequiredMode.NOT_REQUIRED
+        )
         String category,
 
         @Schema(description = "예문")

src/main/java/com/dnd/spaced/domain/skill/presentation/SkillController.java

@@ -18,11 +18,6 @@ public class SkillController {
 
     private final SkillService skillService;
 
-    /**
-     * 퀴즈 결과 저장 API
-     * @param accountInfo 유저 정보
-     * @param request 퀴즈 결과 (카테고리와 맞춘 문제 수)
-     */
     @PostMapping("/save")
     public void addSkill(
             @AuthAccount AuthAccountInfo accountInfo,
@@ -31,21 +26,11 @@ public void addSkill(
         skillService.addSkill(accountInfo, request);
     }
 
-    /**
-     * 전체 능력치 점수 반환 API (카테고리별)
-     * @param accountInfo 유저 정보
-     * @return 카테고리별 스킬 점수 응답 (총점, 맞춘 문제 수, 총 문제 수)
-     */
     @GetMapping("/ability")
     public Map<Category, SkillTotalScoreResponse> getAllAbility(@AuthAccount AuthAccountInfo accountInfo) {
         return skillService.getSkillTotalScore(accountInfo);
     }
 
-    /**
-     * 상위 퍼센트 반환 API
-     * @param info 유저 정보
-     * @return 유저의 상위 퍼센트
-     */
     @GetMapping("/precedence")
     public Long getPrecedence(@AuthAccount AuthAccountInfo info){
         return skillService.getTotalMyScore(info);

src/main/java/com/dnd/spaced/domain/skill/presentation/SwaggerSkillController.java

@@ -0,0 +1,38 @@
+package com.dnd.spaced.domain.skill.presentation;
+
+import com.dnd.spaced.domain.skill.domain.Category;
+import com.dnd.spaced.domain.skill.presentation.dto.request.SkillRequest;
+import com.dnd.spaced.domain.skill.presentation.dto.response.SkillTotalScoreResponse;
+import com.dnd.spaced.global.resolver.auth.AuthAccount;
+import com.dnd.spaced.global.resolver.auth.AuthAccountInfo;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.http.ResponseEntity;
+
+import java.util.Map;
+
+@Tag(name = "능력치 관련 API", description = "퀴즈 결과 저장, 카테고리별 능력치 조회, 상위 퍼센트 조회")
+public interface SwaggerSkillController {
+
+    @Operation(summary = "퀴즈 결과 저장", description = "능력치 계산을 위해 퀴즈 결과(카테고리와 맞춘 문제 수)를 저장합니다.")
+    @ApiResponse(responseCode = "200", description = "OK")
+    ResponseEntity<Void> addSkill(
+            @Parameter(hidden = true) @AuthAccount AuthAccountInfo accountInfo,
+            @RequestBody SkillRequest request
+    );
+
+    @Operation(summary = "카테고리별 능력치 조회", description = "유저의 카테고리별 능력치 점수를 조회합니다. (총점, 맞춘 문제 수, 총 문제 수)")
+    @ApiResponse(responseCode = "200", description = "OK")
+    ResponseEntity<Map<Category, SkillTotalScoreResponse>> getAllAbility(
+            @Parameter(hidden = true) @AuthAccount AuthAccountInfo accountInfo
+    );
+
+    @Operation(summary = "상위 퍼센트 조회", description = "유저가 상위 몇 퍼센트에 해당하는지 조회합니다.")
+    @ApiResponse(responseCode = "200", description = "OK")
+    ResponseEntity<Long> getPrecedence(
+            @Parameter(hidden = true) @AuthAccount AuthAccountInfo accountInfo
+    );
+}