diff --git a/src/main/java/com/book/backend/domain/book/controller/BookController.java b/src/main/java/com/book/backend/domain/book/controller/BookController.java index e044a2f2..4b62b684 100644 --- a/src/main/java/com/book/backend/domain/book/controller/BookController.java +++ b/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, diff --git a/src/main/java/com/book/backend/domain/openapi/dto/response/CustomHotTrendResponseDto.java b/src/main/java/com/book/backend/domain/openapi/dto/response/CustomHotTrendResponseDto.java index 69f027a4..717018c5 100644 --- a/src/main/java/com/book/backend/domain/openapi/dto/response/CustomHotTrendResponseDto.java +++ b/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"; } diff --git a/src/main/java/com/book/backend/domain/openapi/dto/response/HotTrendResponseDto.java b/src/main/java/com/book/backend/domain/openapi/dto/response/HotTrendResponseDto.java index 5b9cad94..175945dd 100644 --- a/src/main/java/com/book/backend/domain/openapi/dto/response/HotTrendResponseDto.java +++ b/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"; } diff --git a/src/main/java/com/book/backend/domain/openapi/dto/response/KeywordResponseDto.java b/src/main/java/com/book/backend/domain/openapi/dto/response/KeywordResponseDto.java index d06c4f9b..a9538063 100644 --- a/src/main/java/com/book/backend/domain/openapi/dto/response/KeywordResponseDto.java +++ b/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: 중요도"; } diff --git a/src/main/java/com/book/backend/domain/openapi/dto/response/RecommendResponseDto.java b/src/main/java/com/book/backend/domain/openapi/dto/response/RecommendResponseDto.java index 67bdb00d..508d9e02 100644 --- a/src/main/java/com/book/backend/domain/openapi/dto/response/RecommendResponseDto.java +++ b/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"; }