Merge pull request #192 from PSR-Co/feat/#189-swagger

[docs] 담당 스웨거 설명 설정

src/main/kotlin/com/psr/psr/cs/controller/CsController.kt

@@ -7,6 +7,9 @@ import com.psr.psr.cs.dto.response.NoticeRes
 import com.psr.psr.cs.service.CsService
 import com.psr.psr.global.dto.BaseResponse
 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 io.swagger.v3.oas.annotations.responses.ApiResponses
 import io.swagger.v3.oas.annotations.security.SecurityRequirement
@@ -23,6 +26,11 @@ class CsController(
         /**
          * 공지사항 메인
          */
+        @Operation(summary = "공지사항 메인(장채은)", description = "공지사항 리스트를 확인한다.")
+        @ApiResponses(
+                value = [
+                        ApiResponse(responseCode = "200", description = "요청에 성공했습니다.")]
+        )
         @GetMapping("/notices")
         fun getNotices(): BaseResponse<NoticeListRes>{
                 return BaseResponse(csService.getNotices())
@@ -31,24 +39,59 @@ class CsController(
         /**
          * 공지사항 상세
          */
+        @Operation(summary = "공지사항 상세(장채은)", description = "공지사항 상세를 확인한다.")
+        @ApiResponses(
+                value = [
+                        ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+                        ApiResponse(
+                                responseCode = "404",
+                                description = "해당 공지사항를 찾을 수 없습니다.",
+                                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+                        )         ]
+        )
         @GetMapping("/notices/{noticeId}")
-        fun getNotice(@PathVariable(name = "noticeId") noticeId: Long): BaseResponse<NoticeRes>{
+        fun getNotice(
+                @Parameter(description = "(Long) 공지사항 Id", example = "1") @PathVariable(name = "noticeId") noticeId: Long): BaseResponse<NoticeRes>{
                 return BaseResponse(csService.getNotice(noticeId))
         }
 
         /**
          * 자주 묻는 질문 메인
          */
+        @Operation(summary = "자주 묻는 질문 메인(장채은)", description = "자주 묻는 질문 리스트를 확인한다.")
+        @ApiResponses(
+                value = [
+                        ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+                        ApiResponse(
+                                responseCode = "400",
+                                description = "올바르지 않은 FAQ 카테고리입니다.",
+                                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+                        )
+                ]
+        )
         @GetMapping("/faqs")
-        fun getFaqs(@RequestParam(value = "type", required = false) type: String?): BaseResponse<FaqListRes>{
+        fun getFaqs(
+                @Parameter(description = "(String) 자주 묻는 질문 타입 (계정관리/컨설팅/상품)", example = "계정관리") @RequestParam(value = "type", required = false) type: String?): BaseResponse<FaqListRes>{
                 return BaseResponse(csService.getFaqs(type))
         }
 
         /**
          * 자주 묻는 질문 상세
          */
+        @Operation(summary = "자주 묻는 질문 상세(장채은)", description = "자주 묻는 질문 상세를 확인한다.")
+        @ApiResponses(
+                value = [
+                        ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+                        ApiResponse(
+                                responseCode = "404",
+                                description = "해당 FAQ를 찾을 수 없습니다.",
+                                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+                        )
+                ]
+        )
         @GetMapping("/faqs/{faqId}")
-        fun getFaq(@PathVariable(name = "faqId") faqId: Long): BaseResponse<FaqRes>{
+        fun getFaq(
+                @Parameter(description = "(Long) 자주 묻는 질문 Id", example = "1") @PathVariable(name = "faqId") faqId: Long): BaseResponse<FaqRes>{
                 return BaseResponse(csService.getFaq(faqId))
         }
 

src/main/kotlin/com/psr/psr/cs/dto/response/FaqListRes.kt

@@ -1,9 +1,11 @@
 package com.psr.psr.cs.dto.response
 
 import com.psr.psr.cs.entity.Faq
+import io.swagger.v3.oas.annotations.media.Schema
 import java.util.stream.Collectors
 
 data class FaqListRes (
+    @Schema(description = "자주 묻는 질문 리스트")
     val faqLists: List<FaqRes>?
 ){
     companion object{

src/main/kotlin/com/psr/psr/cs/dto/response/FaqRes.kt

@@ -2,12 +2,17 @@ package com.psr.psr.cs.dto.response
 
 import com.fasterxml.jackson.annotation.JsonInclude
 import com.psr.psr.cs.entity.Faq
+import io.swagger.v3.oas.annotations.media.Schema
 
 data class FaqRes (
+    @Schema(type = "Long", description = "자주 묻는 질문 id", example = "1")
     val faqId: Long,
+    @Schema(type = "String", description = "자주 묻는 질문 타입", example = "계정관리", allowableValues = ["계정관리", "컨설팅", "상품"])
     val type: String,
+    @Schema(type = "String", description = "자주 묻는 질문 제목", example = "로그아웃이 안돼요.")
     val title: String,
     @JsonInclude(JsonInclude.Include.NON_NULL)
+    @Schema(type = "String", description = "자주 묻는 질문 내용", example = "설정에 들어가면 됩니다.")
     val content: String?= null,
 ){
     companion object{

src/main/kotlin/com/psr/psr/global/exception/BaseResponseCode.kt

@@ -19,10 +19,10 @@ enum class BaseResponseCode(status: HttpStatus, message: String) {
     BLACKLIST_TOKEN(HttpStatus.FORBIDDEN, "로그아웃 혹은 회원 탈퇴된 유저의 토큰 값입니다."),
 
     // user
-    EXISTS_PHONE(HttpStatus.BAD_REQUEST, "이미 가입되어 있는 휴대폰 번호입니다."),
-    EXISTS_EMAIL(HttpStatus.BAD_REQUEST, "이미 가입되어 있는 이메일입니다."),
+    EXISTS_PHONE(HttpStatus.CONFLICT, "이미 가입되어 있는 휴대폰 번호입니다."),
+    EXISTS_EMAIL(HttpStatus.CONFLICT, "이미 가입되어 있는 이메일입니다."),
     EXISTS_MANAGER(HttpStatus.BAD_REQUEST, "관리자는 한 명만 가능합니다."),
-    EXISTS_NICKNAME(HttpStatus.BAD_REQUEST, "이미 가입되어 있는 닉네임입니다."),
+    EXISTS_NICKNAME(HttpStatus.CONFLICT, "이미 가입되어 있는 닉네임입니다."),
     NOT_EXIST_EMAIL(HttpStatus.BAD_REQUEST, "해당 이메일로 가입한 사용자를 찾을 수 없습니다."),
     INVALID_PASSWORD(HttpStatus.BAD_REQUEST, "사용자의 비밀번호가 일치하지 않습니다."),
     NOT_FOUND_USER(HttpStatus.NOT_FOUND, "사용자를 찾을 수 없습니다."),
@@ -34,22 +34,22 @@ enum class BaseResponseCode(status: HttpStatus, message: String) {
     INVALID_EID(HttpStatus.BAD_REQUEST, "정상 사업자가 아닙니다. (휴업자 or 폐업자)"),
     DUPLICATE_PASSWORD(HttpStatus.BAD_REQUEST, "사용자의 비밀번호와 변경하려는 비밀번호가 동일합니다."),
     PHONE_ERROR(HttpStatus.BAD_REQUEST, "naver SMS API 관련 에러입니다."),
-    BLACKLIST_PHONE(HttpStatus.BAD_REQUEST, "SMS 인증코드 유효 시간이 만료되었습니다."),
-    INVALID_SMS_KEY(HttpStatus.BAD_REQUEST, "SMS 인증코드가 알맞지 않습니다. "),
+    BLACKLIST_PHONE(HttpStatus.FORBIDDEN, "SMS 인증코드 유효 시간이 만료되었습니다."),
+    INVALID_SMS_KEY(HttpStatus.BAD_REQUEST, "SMS 인증코드가 알맞지 않습니다."),
 
     // User - type
     INVALID_USER_TYPE_NAME(HttpStatus.BAD_REQUEST, "올바르지 않은 사용자 역할입니다."),
     NO_PERMISSION(HttpStatus.FORBIDDEN, "권한이 없습니다."),
     INVALID_USER_CATEGORY(HttpStatus.BAD_REQUEST, "올바르지 않은 사용자 카테고리입니다."),
 
     // User - category
-    INVALID_USER_INTEREST_COUNT(HttpStatus.BAD_REQUEST, "사용자 관심 주제는 1개이상, 3개 이하여야하며, 중복된 값이 포함되어 있지 않아야 합니다"),
+    INVALID_USER_INTEREST_COUNT(HttpStatus.BAD_REQUEST, "사용자 관심 주제는 1개이상, 3개 이하여야하며, 중복된 값이 포함되어 있지 않아야 합니다."),
 
     // CS - notices
     NOT_FOUND_NOTICE(HttpStatus.NOT_FOUND, "해당 공지사항를 찾을 수 없습니다."),
 
     // CS - faqs
-    INVALID_FAQ_TYPE_NAME(HttpStatus.NOT_FOUND, "올바르지 않은 FAQ 카테고리입니다. "),
+    INVALID_FAQ_TYPE_NAME(HttpStatus.BAD_REQUEST, "올바르지 않은 FAQ 카테고리입니다."),
     NOT_FOUND_FAQ(HttpStatus.NOT_FOUND, "해당 FAQ를 찾을 수 없습니다."),
 
     // report

src/main/kotlin/com/psr/psr/global/jwt/dto/TokenDto.kt

@@ -1,13 +1,17 @@
 package com.psr.psr.global.jwt.dto
 
 import com.psr.psr.global.Constant
+import io.swagger.v3.oas.annotations.media.Schema
 import org.jetbrains.annotations.NotNull
 
 data class TokenDto(
     @field:NotNull
+    @Schema(type = "String", description = "AccessToken", required = true, example = "bearer eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2OTY3NTg2OTcsInVzZXJJZHgiOjEsInN1YiI6IjEifQ.DSBuBlStkjhT05vuzjWd-cg7naG5KikUxII734u3nUw")
     var accessToken: String,
     @field:NotNull
+    @Schema(type = "String", description = "AccessToken", required = true, example = "bearer eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2OTY3NTg2OTcsInVzZXJJZHgiOjEsInN1YiI6IjEifQ.DSBuBlStkjhT05vuzjWd-cg7naG5KikUxII734u3nUw")
     var refreshToken: String,
+    @Schema(type = "String", description = "역할", example = "일반", allowableValues = ["일반", "사업자", "쇼호스트", "관리자"])
     val type: String ?= null
 ){
     companion object{