[merge] RecrodStat api 명세서

Team-Recordy · Jul 15, 2024 · 22044b8 · 22044b8
2 parents 787585e + 5dad5d3
commit 22044b8
Showing 1 changed file with 96 additions and 13 deletions.
diff --git a/src/main/java/org/recordy/server/record_stat/controller/RecordStatApi.java b/src/main/java/org/recordy/server/record_stat/controller/RecordStatApi.java
@@ -7,6 +7,8 @@
 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.recordy.server.auth.security.UserId;
+import org.recordy.server.common.message.ErrorMessage;
+import org.recordy.server.record.domain.Record;
 import org.recordy.server.record.controller.dto.response.RecordInfoWithBookmark;
 import org.recordy.server.record_stat.domain.usecase.Preference;
 import org.springframework.data.domain.Slice;
@@ -15,44 +17,85 @@
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestParam;
 
-@Tag(name = "통계 관련 API")
+@Tag(name = "RecordStat Api")
 public interface RecordStatApi {
 
     @Operation(
-            summary = "북마크 API",
-            description = "북마크를 진행하는 API입니다. ",
+            summary = "레코드 북마크 API",
+            description = "사용자가 특정 레코드를 북마크합니다.",
             responses = {
                     @ApiResponse(
                             responseCode = "200",
-                            description = "성공"
+                            description = "요청이 성공적으로 처리되었습니다.",
+                            content = @Content
+                    ),
+                    @ApiResponse(
+                            responseCode = "404",
+                            description = "Not Found - 존재하지 않는 사용자 또는 레코드입니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
+                    ),
+                    @ApiResponse(
+                            responseCode = "500",
+                            description = "Internal Server Error - 서버 내부 오류입니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
                     )
             }
     )
-    public ResponseEntity bookmark(
+    public ResponseEntity<Void> bookmark(
             @UserId Long userId,
             @PathVariable Long recordId
     );
 
     @Operation(
-            security = @SecurityRequirement(name = "Authorization"),
-            summary = "북마크 삭제 API",
-            description = "access token을 바탕으로 로그아웃을 진행하는 API입니다.",
+            summary = "레코드 북마크 삭제 API",
+            description = "사용자가 특정 레코드의 북마크를 삭제합니다.",
             responses = {
                     @ApiResponse(
                             responseCode = "204",
-                            description = "요청이 성공했습니다."
+                            description = "요청이 성공적으로 처리되었습니다.",
+                            content = @Content
+                    ),
+                    @ApiResponse(
+                            responseCode = "404",
+                            description = "Not Found - 존재하지 않는 사용자 또는 레코드입니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
+                    ),
+                    @ApiResponse(
+                            responseCode = "500",
+                            description = "Internal Server Error - 서버 내부 오류입니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
                     )
             }
     )
-    public ResponseEntity deleteBookmark(
+    public ResponseEntity<Void> deleteBookmark(
             @UserId Long userId,
             @PathVariable Long recordId
     );
 
     @Operation(
             security = @SecurityRequirement(name = "Authorization"),
-            summary = "유저 취향 키워드 top 3 API",
-            description = "유저가 저장, 시청, 올린 영상을 바탕으로 유저 취향 키워드 top 3 API입니다.",
+            summary = "유저 취향 키워드 Top 3 API",
+            description = "유저가 저장, 시청, 올린 영상을 바탕으로 유저 취향 키워드를 반환합니다.",
             responses = {
                     @ApiResponse(
                             responseCode = "200",
@@ -63,6 +106,26 @@ public ResponseEntity deleteBookmark(
                                             implementation = Preference.class
                                     )
                             )
+                    ),
+                    @ApiResponse(
+                            responseCode = "401",
+                            description = "Unauthorized - 인증이 필요합니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
+                    ),
+                    @ApiResponse(
+                            responseCode = "500",
+                            description = "Internal Server Error - 서버 내부 오류입니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
                     )
             }
     )
@@ -76,13 +139,33 @@ public ResponseEntity<Preference> getPreference(
             responses = {
                     @ApiResponse(
                             responseCode = "200",
-                            description = "성공",
+                            description = "요청이 성공적으로 처리되었습니다.",
                             content = @Content(
                                     mediaType = MediaType.APPLICATION_JSON_VALUE,
                                     schema = @Schema(
                                             implementation = Slice.class
                                     )
                             )
+                    ),
+                    @ApiResponse(
+                            responseCode = "401",
+                            description = "Unauthorized - 인증이 필요합니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
+                    ),
+                    @ApiResponse(
+                            responseCode = "500",
+                            description = "Internal Server Error - 서버 내부 오류입니다.",
+                            content = @Content(
+                                    mediaType = MediaType.APPLICATION_JSON_VALUE,
+                                    schema = @Schema(
+                                            implementation = ErrorMessage.class
+                                    )
+                            )
                     )
             }
     )