Merge pull request #37 from BOOK-TALK/#36-swagger

#36 swagger

src/main/java/com/book/backend/domain/book/controller/BookController.java

@@ -12,6 +12,11 @@
 import com.book.backend.domain.openapi.dto.request.RecommendRequestDto;
 import com.book.backend.global.ResponseTemplate;
 import com.book.backend.global.log.RequestLogger;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+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 java.time.LocalDate;
 import java.util.HashSet;
 import java.util.LinkedList;
@@ -34,6 +39,10 @@ public class BookController {
     private final ResponseTemplate responseTemplate;
 
     // 마니아(4), 다독자(5) 추천 API
+    @Operation(summary="책 추천", description="특정 책 코드를 입력으로 받아 해당 책 기반 추천 책 list를 반환합니다.",
+            parameters = {@Parameter(name = "isbn", description = "책 코드")},
+            responses = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = RecommendResponseDto.class)),
+                        description = RecommendResponseDto.description)})
     @GetMapping("/recommend")
     public ResponseEntity<?> recommend(@RequestParam String isbn) throws Exception {
         RequestLogger.param(new String[]{"isbn"}, isbn);
@@ -50,6 +59,9 @@ public ResponseEntity<?> recommend(@RequestParam String isbn) throws Exception {
     }
 
     // 대출급상승(12) API
+    @Operation(summary="대출 급상승", description="지난 3일간 대출 급상승 책 list 를 반환합니다.",
+            responses = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = HotTrendResponseDto.class)),
+                        description = HotTrendResponseDto.description)})
     @GetMapping("/hotTrend")
     public ResponseEntity<?> hotTrend() throws Exception {
         LocalDate yesterday = LocalDate.now().minusDays(1);
@@ -60,6 +72,9 @@ public ResponseEntity<?> hotTrend() throws Exception {
     }
 
     // 지난달 키워드 (17)
+    @Operation(summary="지난달 키워드", description="지난달 핵심 키워드 100개 중 랜덤으로 10개 키워드를 반환합니다.",
+            responses = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = KeywordResponseDto.class)),
+                        description = KeywordResponseDto.description)})
     @GetMapping("/keyword")
     public ResponseEntity<?> keywords() throws Exception {
         KeywordRequestDto requestDto = new KeywordRequestDto();
@@ -70,7 +85,18 @@ public ResponseEntity<?> keywords() throws Exception {
         return responseTemplate.success(response, HttpStatus.OK);
     }
 
-    // 조건형 인기 대출 도서 (3)
+    // 조건형 인기 대출 책 (3)
+    @Operation(summary="조건형 인기 대출 도서", description="조건 값에 따른 인기 대출 책 list 를 반환합니다. (모두 선택값입니다)",
+            parameters = {
+            @Parameter(name = "weekMonth", description = "'week' 또는 'month'"),
+            @Parameter(name = "peerAge", description = "age +- 2 범위의 나이로 또래 인기 대출 책을 조회"),
+            @Parameter(name = "ageRange", description = "연령대 코드 (0, 6, 8, 14, 20, 30, 40, 50, 60)"),
+            @Parameter(name = "gender", description = "'man' 또는 'woman'"),
+            @Parameter(name = "genreCode", description = "세부 장르 코드 (figma 참고)"),
+            @Parameter(name = "region", description = "시단위 지역코드 (figma 참고)"),
+            @Parameter(name = "libCode", description = "도서관 코드 (조회 -> https://www.data4library.kr/libDataL)")},
+            responses = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = CustomHotTrendResponseDto.class)),
+                        description = CustomHotTrendResponseDto.description)})
     @GetMapping("/customHotTrend")
     public ResponseEntity<?> customHotTrend(@RequestParam(required = false) String weekMonth,
                                             @RequestParam(required = false) String peerAge,

src/main/java/com/book/backend/domain/openapi/dto/response/CustomHotTrendResponseDto.java

@@ -25,4 +25,7 @@ public class CustomHotTrendResponseDto implements OpenAPIResponseInterface {
     private String bookImageURL;
     private String bookDtlUrl;
 
+    public static final String description = "no: 순번 | ranking: 순위 | bookname: 책이름 | authors: 작가, 옮긴이 | publisher: 출판사 | "
+            + "publication_year: 출판년도 | isbn13: 책 바코드 | additional_symbol: 책 바코드 부가기호? | vol: 권? | class_no: 주제코드 | "
+            + "class_nm: 주제분류 | loan_count: 대출횟수 | bookImageURL: 책표지 URL | bookDtlUrl: 책 상세정보 URL";
 }

src/main/java/com/book/backend/domain/openapi/dto/response/HotTrendResponseDto.java

@@ -25,4 +25,9 @@ public class HotTrendResponseDto implements OpenAPIResponseInterface {
     private String class_nm;
     private String bookImageURL;
     private String bookDtlUrl;
+
+    public static final String description = "no: 순번 | difference: 대출순위 상승폭 | baseWeekRank: 기준일 순위 | pastWeekRank: 전주 순위 | "
+            + "bookname: 책이름 | authors: 작가, 옮긴이 | publisher: 출판사 | publication_year: 출판년도 | isbn13: 책 바코드 | "
+            + "additional_symbol: 책 바코드 부가기호? | vol: 권? | class_no: 주제코드 | class_nm: 주제분류 | bookImageURL: 책표지 URL | "
+            + "bookDtlUrl: 책 상세정보 URL";
 }

src/main/java/com/book/backend/domain/openapi/dto/response/KeywordResponseDto.java

@@ -12,4 +12,6 @@
 public class KeywordResponseDto implements OpenAPIResponseInterface{
     private String keyword;
     private String weight; // 중요도
+
+    public static final String description = "keyword: 검색어 | weight: 중요도";
 }

src/main/java/com/book/backend/domain/openapi/dto/response/RecommendResponseDto.java

@@ -20,5 +20,9 @@ public class RecommendResponseDto implements OpenAPIResponseInterface {
     private String class_no;
     private String class_nm;
     private String bookImageURL;
+
+    public static final String description = "bookname: 책이름 | authors: 작가 옮긴이 | publisher: 출판사 | "
+            + "publication_year: 출판년도 | isbn13: 책 바코드 | additional_symbol: 책 바코드 부가기호? | vol: 권? | "
+            + "class_no: 주제코드 | class_nm: 주제분류 | bookImageURL: 책표지 URL";
 }