[DVK-63] fix: 전자책 API에 Swagger 적용

src/main/kotlin/com/devooks/backend/auth/v1/controller/AuthControllerDocs.kt

@@ -8,47 +8,79 @@ import com.devooks.backend.auth.v1.dto.LogoutRequest
 import com.devooks.backend.auth.v1.dto.LogoutResponse
 import com.devooks.backend.auth.v1.dto.ReissueRequest
 import com.devooks.backend.auth.v1.dto.ReissueResponse
+import com.devooks.backend.common.exception.ErrorResponse
 import io.swagger.v3.oas.annotations.Operation
 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 io.swagger.v3.oas.annotations.responses.ApiResponses
 import io.swagger.v3.oas.annotations.tags.Tag
+import org.springframework.http.MediaType.APPLICATION_JSON_VALUE
 
 @Tag(name = "인증 API")
 interface AuthControllerDocs {
 
     @Operation(summary = "로그인")
     @ApiResponses(
         value = [
-            ApiResponse(responseCode = "200", description = "OK"),
+            ApiResponse(
+                responseCode = "200",
+                description = "OK",
+                content = [
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = LoginResponse::class)
+                    )
+                ]
+            ),
             ApiResponse(
                 responseCode = "400",
                 description =
                 "- AUTH-400-1 : 인증 코드(authorizationCode)가 NULL이거나 빈 문자일 경우\n" +
                         "- AUTH-400-2 : 인증 유형(oauthType)이 NAVER, KAKAO, GOOGLE 이 아닐 경우 ",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "401",
                 description =
                 "- AUTH-401-3 : 네이버 로그인을 실패할 경우\n" +
                         "- AUTH-401-4 : 카카오 로그인을 실패할 경우\n" +
                         "- AUTH-401-5 : 구글 로그인을 실패할 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "403",
                 description =
                 "- AUTH-403-1 : 정지된 회원일 경우 경우\n" +
                         "- AUTH-403-2 : 탈퇴한 회원일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "404",
                 description =
-                "- MEMBER-404-1 : 회원을 찾을 수 없는 경우 (message에 oauthId를 넣어서 응답)",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                "- MEMBER-404-1 : 회원을 찾을 수 없는 경우 " +
+                        "(message에 oauthId를 넣어서 응답, {\"oauthId\" : \":oauthId\"})",
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             )
         ]
     )
@@ -58,24 +90,48 @@ interface AuthControllerDocs {
     @Operation(summary = "로그아웃")
     @ApiResponses(
         value = [
-            ApiResponse(responseCode = "200", description = "OK"),
+            ApiResponse(
+                responseCode = "200",
+                description = "OK",
+                content = [
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = LogoutResponse::class)
+                    )
+                ]
+            ),
             ApiResponse(
                 responseCode = "400",
                 description =
                 "- AUTH-400-3 : 리프래시 토큰(refreshToken)이 NULL이거나 빈 문자일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "401",
                 description =
                 "- AUTH-401-1 : 기간이 만료된 토큰일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "403",
                 description =
                 "- AUTH-403-1 : 잘못된 형식의 토큰일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             )
         ]
     )
@@ -84,31 +140,60 @@ interface AuthControllerDocs {
     @Operation(summary = "토큰 재발급")
     @ApiResponses(
         value = [
-            ApiResponse(responseCode = "200", description = "OK"),
+            ApiResponse(
+                responseCode = "200",
+                description = "OK",
+                content = [
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ReissueResponse::class)
+                    )
+                ]
+            ),
             ApiResponse(
                 responseCode = "400",
                 description =
                 "- AUTH-400-3 : 리프래시 토큰(refreshToken)이 NULL이거나 빈 문자일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "401",
                 description =
                 "- AUTH-401-1 : 기간이 만료된 토큰일 경우\n" +
                         "- AUTH-401-2 : 원본 리프래시 토큰과 일치하지 않을 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "403",
                 description =
                 "- AUTH-403-1 : 잘못된 형식의 토큰일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "404",
                 description =
                 "- AUTH-404-1 : 리프래시 토큰이 존재하지 않을 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             )
         ]
     )
@@ -117,19 +202,38 @@ interface AuthControllerDocs {
     @Operation(summary = "이메일 확인")
     @ApiResponses(
         value = [
-            ApiResponse(responseCode = "200", description = "OK"),
+            ApiResponse(
+                responseCode = "200",
+                description = "OK",
+                content = [
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = CheckEmailResponse::class)
+                    )
+                ]
+            ),
             ApiResponse(
                 responseCode = "400",
                 description =
                 "- AUTH-400-16 : 이메일 값이 존재하지 않을 경우" +
                         "- AUTH-400-17 : 이메일 형식이 아닐 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             ),
             ApiResponse(
                 responseCode = "500",
                 description =
-                    "- AUTH-500-4 : 이메일 전송을 실패했을 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
+                "- AUTH-500-4 : 이메일 전송을 실패했을 경우",
+                content = arrayOf(
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = ErrorResponse::class)
+                    )
+                )
             )
         ]
     )

src/main/kotlin/com/devooks/backend/auth/v1/dto/CheckEmailResponse.kt

@@ -1,5 +1,8 @@
 package com.devooks.backend.auth.v1.dto
 
+import io.swagger.v3.oas.annotations.media.Schema
+
 data class CheckEmailResponse(
+    @Schema(description = "결과 메시지", example = "이메일 인증이 완료됐습니다.")
     val message: String = "이메일 인증이 완료됐습니다."
 )

src/main/kotlin/com/devooks/backend/auth/v1/dto/LoginRequest.kt

@@ -7,12 +7,17 @@ import io.swagger.v3.oas.annotations.media.Schema
 data class LoginRequest(
     @Schema(description = "OAuth2 인증 코드", required = true, nullable = false)
     val authorizationCode: String?,
-    @Schema(description = "OAuth2 인증 유형", required = true, nullable = false, example = "NAVER")
-    val oauthType: String?
+    @Schema(
+        description = "OAuth2 인증 유형 (ex. NAVER, KAKAO, GOOGLE)",
+        required = true,
+        nullable = false,
+        example = "NAVER"
+    )
+    val oauthType: String?,
 ) {
     fun toCommand(): LoginCommand =
         LoginCommand(
             authorizationCode = authorizationCode.validateAuthorizationCode(),
             oauthType = oauthType.validateOauthType()
         )
-}
+}

src/main/kotlin/com/devooks/backend/auth/v1/dto/LogoutResponse.kt

@@ -1,5 +1,8 @@
 package com.devooks.backend.auth.v1.dto
 
+import io.swagger.v3.oas.annotations.media.Schema
+
 data class LogoutResponse(
+    @Schema(description = "결과 메시지", example = "로그아웃이 완료됐습니다.")
     val message: String = "로그아웃이 완료됐습니다."
 )

src/main/kotlin/com/devooks/backend/category/v1/controller/CategoryControllerDocs.kt

@@ -2,14 +2,30 @@ package com.devooks.backend.category.v1.controller
 
 import com.devooks.backend.category.v1.dto.GetCategoriesResponse
 import io.swagger.v3.oas.annotations.Operation
+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 io.swagger.v3.oas.annotations.responses.ApiResponses
 import io.swagger.v3.oas.annotations.tags.Tag
+import org.springframework.http.MediaType.APPLICATION_JSON_VALUE
 
 @Tag(name = "카테고리 API")
 interface CategoryControllerDocs {
 
     @Operation(summary = "카테고리 목록 조회")
-    @ApiResponses(value = [ApiResponse(responseCode = "200", description = "OK")])
+    @ApiResponses(
+        value = [
+            ApiResponse(
+                responseCode = "200",
+                description = "OK",
+                content = [
+                    Content(
+                        mediaType = APPLICATION_JSON_VALUE,
+                        schema = Schema(implementation = GetCategoriesResponse::class)
+                    )
+                ]
+            )
+        ]
+    )
     suspend fun getCategories(): GetCategoriesResponse
 }

src/main/kotlin/com/devooks/backend/category/v1/dto/CategoryDto.kt

@@ -1,10 +1,13 @@
 package com.devooks.backend.category.v1.dto
 
 import com.devooks.backend.category.v1.domain.Category
+import io.swagger.v3.oas.annotations.media.Schema
 import java.util.*
 
 data class CategoryDto(
+    @Schema(description = "카테고리 식별자")
     val id: UUID,
+    @Schema(description = "카테고리 이름")
     val name: String,
 ) {
     companion object {
@@ -14,4 +17,4 @@ data class CategoryDto(
                 name = name
             )
     }
-}
+}

src/main/kotlin/com/devooks/backend/common/exception/ErrorResponse.kt

@@ -0,0 +1,21 @@
+package com.devooks.backend.common.exception
+
+import io.swagger.v3.oas.annotations.media.Schema
+import java.util.*
+
+class ErrorResponse(
+    @Schema(description = "에러 발생 날짜", example = "2024-11-04T05:05:43.264+00:00")
+    val timestamp: Date,
+    @Schema(description = "에러 발생 API 경로", example = "/api/v1/ebook-inquiry-comments")
+    val path: String,
+    @Schema(description = "에러 상태 코드", example = "400")
+    val status: Int,
+    @Schema(description = "에러 유형", example = "BAD_REQUEST")
+    val error: String,
+    @Schema(description = "요청 식별자", example = "ebad5bcb-5")
+    val requestId: String,
+    @Schema(description = "에러 코드", example = "EBOOK-400-11")
+    val code: String,
+    @Schema(description = "에러 메시지", example = "문의 식별자가 반드시 필요합니다.")
+    val message: String,
+)