feat: 알라딘 외부 API 도서검색 및 상세 조회 기능

admin/src/main/resources/application.yml

@@ -9,10 +9,12 @@ spring:
         - persistence
         - jwt
         - redis
+        - external
       prod:
         - persistence
         - jwt
         - redis
+        - external
       test:
         - persistence
         - jwt

apis/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
     implementation(project(Dependencies.Projects.GATEWAY))
 
     implementation(Dependencies.Spring.BOOT_STARTER_WEB)
-    testImplementation(Dependencies.Spring.BOOT_STARTER_TEST)
     implementation(Dependencies.Spring.BOOT_STARTER_DATA_JPA)
     implementation(Dependencies.Spring.BOOT_STARTER_SECURITY)
     implementation(Dependencies.Spring.BOOT_STARTER_VALIDATION)
@@ -22,11 +21,12 @@ dependencies {
     implementation(Dependencies.Swagger.SPRINGDOC_OPENAPI_STARTER_WEBMVC_UI)
 
     implementation(Dependencies.Logging.KOTLIN_LOGGING)
-    implementation(Dependencies.Feign.STARTER_OPENFEIGN)
 
+    testImplementation(Dependencies.Spring.BOOT_STARTER_TEST)
     testImplementation(Dependencies.TestContainers.MYSQL)
     testImplementation(Dependencies.TestContainers.JUNIT_JUPITER)
     testImplementation(Dependencies.TestContainers.REDIS)
+
 }
 
 tasks {

apis/src/main/kotlin/org/yapp/apis/book/controller/BookController.kt

@@ -0,0 +1,35 @@
+package org.yapp.apis.book.controller
+
+import jakarta.validation.Valid
+import org.springframework.http.ResponseEntity
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.ModelAttribute
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+import org.yapp.apis.book.dto.request.BookDetailRequest
+import org.yapp.apis.book.dto.request.BookSearchRequest
+import org.yapp.apis.book.dto.response.BookDetailResponse
+import org.yapp.apis.book.dto.response.BookSearchResponse
+import org.yapp.apis.book.usecase.BookUseCase
+
+
+@RestController
+@RequestMapping("/api/v1/books")
+class BookController(
+    private val bookUseCase: BookUseCase
+) : BookControllerApi {
+
+    @GetMapping("/search")
+    override fun searchBooks(@Valid @ModelAttribute request: BookSearchRequest): ResponseEntity<BookSearchResponse> {
+        val response = bookUseCase.searchBooks(request)
+        return ResponseEntity.ok(response)
+    }
+
+    @GetMapping("/detail")
+    override fun getBookDetail(
+        @Valid @ModelAttribute request: BookDetailRequest
+    ): ResponseEntity<BookDetailResponse> {
+        val response = bookUseCase.getBookDetail(request)
+        return ResponseEntity.ok(response)
+    }
+}

apis/src/main/kotlin/org/yapp/apis/book/controller/BookControllerApi.kt

@@ -0,0 +1,113 @@
+package org.yapp.apis.book.controller
+
+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.ExampleObject
+import io.swagger.v3.oas.annotations.media.Schema
+import io.swagger.v3.oas.annotations.responses.ApiResponse
+import io.swagger.v3.oas.annotations.responses.ApiResponses
+import io.swagger.v3.oas.annotations.tags.Tag
+import jakarta.validation.Valid
+import org.springframework.http.ResponseEntity
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.RequestMapping
+import org.yapp.apis.book.dto.request.BookDetailRequest
+import org.yapp.apis.book.dto.request.BookSearchRequest
+import org.yapp.apis.book.dto.response.BookDetailResponse
+import org.yapp.apis.book.dto.response.BookSearchResponse
+
+/**
+ * API interface for book controller.
+ */
+@Tag(name = "Books", description = "도서 정보를 조회하는 API")
+@RequestMapping("/api/v1/books")
+interface BookControllerApi {
+
+    @Operation(
+        summary = "도서 검색",
+        description = "키워드를 사용하여 알라딘 도서 정보를 검색합니다."
+    )
+    @ApiResponses(
+        value = [
+            ApiResponse(
+                responseCode = "200",
+                description = "성공적인 검색",
+                content = [Content(schema = Schema(implementation = BookSearchResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "400",
+                description = "잘못된 요청 파라미터"
+            )
+        ]
+    )
+    @GetMapping("/search")
+    fun searchBooks(
+        @Valid
+        @Parameter(
+            description = "도서 검색 요청 객체. 다음 쿼리 파라미터를 포함합니다:<br>" +
+                    "- `query` (필수): 검색어 <br>" +
+                    "- `queryType` (선택): 검색어 타입 (예: Title, Author). 기본값은 All <br>" +
+                    "- `maxResults` (선택): 한 페이지당 결과 개수 (1-50). 기본값 10 <br>" +
+                    "- `start` (선택): 결과 시작 페이지. 기본값 1 <br>" +
+                    "- `sort` (선택): 정렬 방식 (예: PublishTime, SalesPoint). 기본값 Accuracy <br>" +
+                    "- `categoryId` (선택): 카테고리 ID",
+            examples = [
+                ExampleObject(name = "기본 검색", value = "http://localhost:8080/api/v1/books/search?query=코틀린"),
+                ExampleObject(
+                    name = "상세 검색",
+                    value = "http://localhost:8080/api/v1/books/search?query=클린코드&queryType=Title&maxResults=10&sort=PublishTime"
+                ),
+                ExampleObject(
+                    name = "카테고리 검색",
+                    value = "http://localhost:8080/api/v1/books/search?query=Spring&categoryId=170&start=2&maxResults=5"
+                )
+            ]
+        )
+        request: BookSearchRequest
+    ): ResponseEntity<BookSearchResponse>
+
+
+    @Operation(
+        summary = "도서 상세 조회",
+        description = "특정 도서의 상세 정보를 조회합니다. `itemId`는 쿼리 파라미터로 전달됩니다."
+    )
+    @ApiResponses(
+        value = [
+            ApiResponse(
+                responseCode = "200",
+                description = "성공적으로 도서 상세 정보를 조회했습니다.",
+                content = [Content(schema = Schema(implementation = BookDetailResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "400",
+                description = "잘못된 요청 파라미터 (예: 유효하지 않은 itemId 또는 itemIdType)"
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당하는 itemId를 가진 도서를 찾을 수 없습니다."
+            )
+        ]
+    )
+    @GetMapping("/detail")
+    fun getBookDetail(
+        @Valid
+        @Parameter(
+            description = "도서 상세 조회 요청 객체. 다음 쿼리 파라미터를 포함합니다:<br>" +
+                    "- `itemId` (필수): 조회할 도서의 고유 ID (ISBN, ISBN13, 알라딘 ItemId 등)<br>" +
+                    "- `itemIdType` (선택): `itemId`의 타입 (ISBN, ISBN13, ItemId). 기본값은 ISBN입니다.<br>" +
+                    "- `optResult` (선택): 조회할 부가 정보 목록 (쉼표로 구분). 예시: `BookInfo,Toc,PreviewImg`",
+            examples = [
+                ExampleObject(
+                    name = "ISBN으로 상세 조회",
+                    value = "http://localhost:8080/api/v1/books/detail?itemId=9791162241684&itemIdType=ISBN13"
+                ),
+                ExampleObject(
+                    name = "ISBN 및 부가 정보 포함",
+                    value = "http://localhost:8080/api/v1/books/detail?itemId=8994492040&itemIdType=ISBN&optResult=BookInfo,Toc"
+                )
+            ]
+        )
+        request: BookDetailRequest
+    ): ResponseEntity<BookDetailResponse>
+}

apis/src/main/kotlin/org/yapp/apis/book/dto/request/BookDetailRequest.kt

@@ -0,0 +1,25 @@
+package org.yapp.apis.book.dto.request
+
+import jakarta.validation.constraints.NotBlank
+import jakarta.validation.constraints.Pattern // Pattern 어노테이션 추가
+import org.yapp.globalutils.util.RegexUtils
+import org.yapp.infra.external.aladin.dto.AladinBookLookupRequest
+
+data class BookDetailRequest private constructor(
+    @field:NotBlank(message = "아이템 ID는 필수입니다.")
+    @field:Pattern(
+        regexp = RegexUtils.NOT_BLANK_AND_NOT_NULL_STRING_PATTERN,
+        message = "아이템 ID는 유효한 ISBN 형식이 아닙니다."
+    )
+    val itemId: String? = null,
+    val itemIdType: String? = "ISBN",
+    val optResult: List<String>? = null
+) {
+    fun toAladinRequest(): AladinBookLookupRequest {
+        return AladinBookLookupRequest.create(
+            itemId = this.itemId!!,
+            itemIdType = this.itemIdType ?: "ISBN",
+            optResult = this.optResult
+        )
+    }
+}

apis/src/main/kotlin/org/yapp/apis/book/dto/request/BookSearchRequest.kt

@@ -0,0 +1,31 @@
+package org.yapp.apis.book.dto.request
+
+import org.yapp.infra.external.aladin.dto.AladinBookSearchRequest
+
+
+data class BookSearchRequest private constructor(
+    val query: String? = null,
+    val queryType: String? = null,
+    val searchTarget: String? = null,
+    val maxResults: Int? = null,
+    val start: Int? = null,
+    val sort: String? = null,
+    val cover: String? = null,
+    val categoryId: Int? = null
+) {
+
+    fun validQuery(): String = query!!
+    fun toAladinRequest(): AladinBookSearchRequest {
+
+        return AladinBookSearchRequest.create(
+            query = this.validQuery(),
+            queryType = this.queryType,
+            searchTarget = this.searchTarget,
+            maxResults = this.maxResults,
+            start = this.start,
+            sort = this.sort,
+            cover = this.cover,
+            categoryId = this.categoryId
+        )
+    }
+}

apis/src/main/kotlin/org/yapp/apis/book/dto/response/BookDetailResponse.kt

@@ -0,0 +1,60 @@
+package org.yapp.apis.book.dto.response
+
+import org.yapp.infra.external.aladin.response.AladinBookDetailResponse
+import java.math.BigDecimal
+
+/**
+ * 단일 도서의 상세 정보를 나타내는 DTO.
+ * 외부 API 응답 및 도메인 Book 객체로부터 변환됩니다.
+ */
+data class BookDetailResponse private constructor(
+    val version: String?,
+    val title: String,
+    val link: String?,
+    val author: String?,
+    val pubDate: String?,
+    val description: String?,
+    val isbn: String?,
+    val isbn13: String?,
+    val itemId: Long?,
+    val priceSales: BigDecimal?,
+    val priceStandard: BigDecimal?,
+    val mallType: String?,
+    val stockStatus: String?,
+    val mileage: Int?,
+    val cover: String?,
+    val categoryId: Int?,
+    val categoryName: String?,
+    val publisher: String?
+) {
+    companion object {
+        /**
+         * AladinBookDetailResponse와 Book 도메인 객체로부터 BookDetailResponse를 생성합니다.
+         */
+        fun from(response: AladinBookDetailResponse): BookDetailResponse {
+            val bookItem = response.item?.firstOrNull()
+                ?: throw IllegalArgumentException("No book item found in detail response.")
+
+            return BookDetailResponse(
+                version = response.version,
+                title = bookItem.title ?: "",
+                link = bookItem.link,
+                author = bookItem.author ?: "",
+                pubDate = bookItem.pubDate,
+                description = bookItem.description ?: "",
+                isbn = bookItem.isbn ?: bookItem.isbn13 ?: "",
+                isbn13 = bookItem.isbn13,
+                itemId = bookItem.itemId,
+                priceSales = bookItem.priceSales,
+                priceStandard = bookItem.priceStandard,
+                mallType = bookItem.mallType,
+                stockStatus = bookItem.stockStatus,
+                mileage = bookItem.mileage,
+                cover = bookItem.cover ?: "",
+                categoryId = bookItem.categoryId,
+                categoryName = bookItem.categoryName,
+                publisher = bookItem.publisher ?: "",
+            )
+        }
+    }
+}

apis/src/main/kotlin/org/yapp/apis/book/dto/response/BookSearchResponse.kt

@@ -0,0 +1,60 @@
+package org.yapp.apis.book.dto.response
+
+import org.yapp.infra.external.aladin.response.AladinSearchResponse
+import org.yapp.infra.external.aladin.response.BookItem
+
+data class BookSearchResponse private constructor(
+    val version: String?,
+    val title: String?,
+    val link: String?,
+    val pubDate: String?,
+    val totalResults: Int?,
+    val startIndex: Int?,
+    val itemsPerPage: Int?,
+    val query: String?,
+    val searchCategoryId: Int?,
+    val searchCategoryName: String?,
+    val books: List<BookSummary>
+) {
+    companion object {
+        fun from(response: AladinSearchResponse): BookSearchResponse {
+            val books = response.item?.mapNotNull { BookSummary.fromAladinItem(it) } ?: emptyList()
+            return BookSearchResponse(
+                version = response.version,
+                title = response.title,
+                link = response.link,
+                pubDate = response.pubDate,
+                totalResults = response.totalResults,
+                startIndex = response.startIndex,
+                itemsPerPage = response.itemsPerPage,
+                query = response.query,
+                searchCategoryId = response.searchCategoryId,
+                searchCategoryName = response.searchCategoryName,
+                books = books
+            )
+        }
+    }
+
+    data class BookSummary private constructor(
+        val isbn: String,
+        val title: String,
+        val author: String?,
+        val publisher: String?,
+        val coverImageUrl: String?,
+    ) {
+        companion object {
+            private val unknownTitle = "제목없음"
+
+            fun fromAladinItem(item: BookItem): BookSummary? {
+                val isbn = item.isbn ?: item.isbn13 ?: return null
+                return BookSummary(
+                    isbn = isbn,
+                    title = item.title ?: unknownTitle,
+                    author = item.author,
+                    publisher = item.publisher,
+                    coverImageUrl = item.cover
+                )
+            }
+        }
+    }
+}