Merge pull request #25 from LeeSM0518/DVK-83-apply-swagger-to-member-api

[DVK-83] docs: 회원 API에 Swagger 적용
LeeSM0518 · Nov 5, 2024 · fc04f4e · fc04f4e
2 parents b531313 + d24944c
commit fc04f4e
Show file tree

Hide file tree

Showing 17 changed files with 465 additions and 51 deletions.
diff --git a/src/main/kotlin/com/devooks/backend/auth/v1/domain/TokenGroup.kt b/src/main/kotlin/com/devooks/backend/auth/v1/domain/TokenGroup.kt
@@ -1,9 +1,13 @@
 package com.devooks.backend.auth.v1.domain
 
+import io.swagger.v3.oas.annotations.media.Schema
+
 typealias AccessToken = String
 typealias RefreshToken = String
 
 data class TokenGroup(
+    @Schema(description = "액세스 토큰")
     val accessToken: AccessToken,
+    @Schema(description = "리프래시 토큰")
     val refreshToken: RefreshToken,
-)
+)
diff --git a/src/main/kotlin/com/devooks/backend/category/v1/domain/Category.kt b/src/main/kotlin/com/devooks/backend/category/v1/domain/Category.kt
@@ -1,13 +1,16 @@
 package com.devooks.backend.category.v1.domain
 
 import com.devooks.backend.category.v1.entity.CategoryEntity
+import io.swagger.v3.oas.annotations.media.Schema
 import java.util.*
 
 class Category(
+    @Schema(description = "카테고리 식별자")
     val id: UUID,
+    @Schema(description = "카테고리 이름")
     val name: String,
 ) {
     companion object {
         fun CategoryEntity.toDomain() = Category(id = this.id!!, name = this.name)
     }
-}
+}
diff --git a/src/main/kotlin/com/devooks/backend/common/dto/ImageDto.kt b/src/main/kotlin/com/devooks/backend/common/dto/ImageDto.kt
@@ -6,11 +6,16 @@ import com.devooks.backend.common.domain.ImageExtension.Companion.validateImageE
 import com.devooks.backend.common.error.CommonError
 import com.devooks.backend.common.error.validateImageOrder
 import com.devooks.backend.common.error.validateNotBlank
+import io.swagger.v3.oas.annotations.media.Schema
 
 data class ImageDto(
+    @Schema(description = "base64 프로필 사진", required = true, nullable = false)
     val base64Raw: String?,
+    @Schema(description = "확장자 (ex. JPG, PNG, JPEG)", required = true, nullable = false)
     val extension: String?,
+    @Schema(description = "파일 크기 (byte, 최대 50MB)", required = true, nullable = false)
     val byteSize: Long?,
+    @Schema(description = "파일 순서", required = true, nullable = false)
     val order: Int?
 ) {
     fun toDomain(): Image =
@@ -20,4 +25,4 @@ data class ImageDto(
             byteSize = byteSize.validateByteSize(),
             order = order.validateImageOrder()
         )
-}
+}
diff --git a/src/main/kotlin/com/devooks/backend/common/error/CommonError.kt b/src/main/kotlin/com/devooks/backend/common/error/CommonError.kt
@@ -9,7 +9,13 @@ enum class CommonError(val exception: GeneralException) {
     INVALID_PAGE(GeneralException("COMMON-400-1", BAD_REQUEST, "페이지는 1부터 조회할 수 있습니다.")),
     INVALID_COUNT(GeneralException("COMMON-400-2", BAD_REQUEST, "개수는 1~1000 까지 조회할 수 있습니다.")),
     REQUIRED_BASE64RAW(GeneralException("COMMON-400-3", BAD_REQUEST, "이미지 내용이 반드시 필요합니다.")),
-    INVALID_IMAGE_EXTENSION(GeneralException("COMMON-400-4", BAD_REQUEST, "유효하지 않은 이미지 확장자입니다.")),
+    INVALID_IMAGE_EXTENSION(
+        GeneralException(
+            "COMMON-400-4",
+            BAD_REQUEST,
+            "유효하지 않은 이미지 확장자입니다. JPG, PNG, JPEG만 가능합니다."
+        )
+    ),
     INVALID_BYTE_SIZE(GeneralException("COMMON-400-5", BAD_REQUEST, "50MB 이하의 영상만 저장이 가능합니다.")),
     REQUIRED_IMAGE(GeneralException("COMMON-400-6", BAD_REQUEST, "이미지가 반드시 필요합니다.")),
     INVALID_IMAGE_ORDER(GeneralException("COMMON-400-7", BAD_REQUEST, "유효하지 않은 이미지 순서입니다.")),
@@ -23,4 +29,4 @@ enum class CommonError(val exception: GeneralException) {
     override fun toString(): String {
         return "CommonError(exception=$exception)"
     }
-}
+}
diff --git a/src/main/kotlin/com/devooks/backend/member/v1/controller/MemberController.kt b/src/main/kotlin/com/devooks/backend/member/v1/controller/MemberController.kt
@@ -27,11 +27,6 @@ import com.devooks.backend.member.v1.dto.WithdrawMemberResponse
 import com.devooks.backend.member.v1.service.FavoriteCategoryService
 import com.devooks.backend.member.v1.service.MemberInfoService
 import com.devooks.backend.member.v1.service.MemberService
-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 java.util.*
 import org.springframework.http.HttpHeaders.AUTHORIZATION
@@ -54,38 +49,11 @@ class MemberController(
     private val categoryService: CategoryService,
     private val favoriteCategoryService: FavoriteCategoryService,
     private val tokenService: TokenService,
-) {
+): MemberControllerDocs {
 
-    @Operation(summary = "회원가입")
-    @ApiResponses(
-        value = [
-            ApiResponse(responseCode = "200", description = "OK"),
-            ApiResponse(
-                responseCode = "400",
-                description =
-                "- AUTH-400-1 : 인증 코드(authorizationCode)가 NULL이거나 빈 문자일 경우\n" +
-                        "- AUTH-400-2 : 인증 유형(oauthType)이 NAVER, KAKAO, GOOGLE 이 아닐 경우\n" +
-                        "- MEMBER-400-1 : 닉네임(nickname)이 2~12 글자가 아닐 경우\n" +
-                        "- MEMBER-400-2 : 관심 카테고리(favoriteCategories)가 NULL일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
-            ),
-            ApiResponse(
-                responseCode = "403",
-                description =
-                "- MEMBER-403-1 : 정지된 회원일 경우\n" +
-                        "- MEMBER-403-2 : 탈퇴한 회원일 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
-            ),
-            ApiResponse(
-                responseCode = "409",
-                description = "- MEMBER-409-1 : 닉네임이 이미 존재할 경우",
-                content = arrayOf(Content(schema = Schema(hidden = true)))
-            )
-        ]
-    )
     @Transactional
     @PostMapping("/signup")
-    suspend fun signUp(
+    override suspend fun signUp(
         @RequestBody
         request: SignUpRequest,
     ): SignUpResponse {
@@ -103,7 +71,7 @@ class MemberController(
 
     @Transactional
     @PatchMapping("/account")
-    suspend fun modifyAccountInfo(
+    override suspend fun modifyAccountInfo(
         @RequestBody
         request: ModifyAccountInfoRequest,
         @RequestHeader(AUTHORIZATION)
@@ -117,7 +85,7 @@ class MemberController(
 
     @Transactional
     @PatchMapping("/image")
-    suspend fun modifyProfileImage(
+    override suspend fun modifyProfileImage(
         @RequestBody
         request: ModifyProfileImageRequest,
         @RequestHeader(AUTHORIZATION)
@@ -131,7 +99,7 @@ class MemberController(
 
     @Transactional
     @PatchMapping("/nickname")
-    suspend fun modifyNickname(
+    override suspend fun modifyNickname(
         @RequestBody
         request: ModifyNicknameRequest,
         @RequestHeader(AUTHORIZATION)
@@ -145,7 +113,7 @@ class MemberController(
 
     @Transactional
     @PatchMapping("/profile")
-    suspend fun modifyProfile(
+    override suspend fun modifyProfile(
         @RequestBody
         request: ModifyProfileRequest,
         @RequestHeader(AUTHORIZATION)
@@ -163,8 +131,8 @@ class MemberController(
     }
 
     @GetMapping("/{memberId}/profile")
-    suspend fun getProfile(
-        @PathVariable
+    override suspend fun getProfile(
+        @PathVariable(required = true)
         memberId: UUID,
     ): GetProfileResponse {
         val member: Member = memberService.findById(memberId)
@@ -175,7 +143,7 @@ class MemberController(
 
     @Transactional
     @PatchMapping("/withdrawal")
-    suspend fun withdrawMember(
+    override suspend fun withdrawMember(
         @RequestBody
         request: WithdrawMemberRequest,
         @RequestHeader(AUTHORIZATION)