Merge pull request #193 from PSR-Co/docs/#188-swagger

[docs] 리뷰, 요청, 알림, 문의 스웨거 설명 설정

src/main/kotlin/com/psr/psr/inquiry/controller/InquiryController.kt

@@ -33,7 +33,10 @@ class InquiryController(
             ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
             ApiResponse(
                 responseCode = "400",
-                description = "제목을 입력해주세요. 제목은 최대 100자입니다. 내용을 입력해주세요. 내용은 최대 250자입니다.",
+                description = "제목을 입력해주세요.<br>" +
+                        "제목은 최대 100자입니다.<br>" +
+                        "내용을 입력해주세요.<br>" +
+                        "내용은 최대 250자입니다.",
                 content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
             )]
     )
@@ -46,6 +49,16 @@ class InquiryController(
     }
 
     // 문의하기 상세 조회
+    @Operation(summary = "문의하기 상세 조회(박서연)", description = "문의 내역 상세조회를 한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 문의를 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @GetMapping("/{inquiryId}")
     fun getInquiryDetails(
         @AuthenticationPrincipal userAccount: UserAccount,
@@ -55,29 +68,80 @@ class InquiryController(
     }
 
     // 문의하기 목록 조회
+    @Operation(summary = "문의하기 목록 조회(박서연)", description = "문의 내역 목록을 조회한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "400",
+                description = "올바르지 않은 문의 상태입니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @GetMapping
     fun getInquiryList(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @RequestParam status: String
+        @Parameter(description = "(String) 문의 상태", example = "진행중/완료") @RequestParam status: String
     ): BaseResponse<InquiryListRes?> {
         return BaseResponse(inquiryService.getInquiryList(userAccount.getUser(), status))
     }
 
     // 문의하기 답변 등록
+    @Operation(summary = "문의하기 답변 등록(박서연)", description = "문의하기의 답변을 등록한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "400",
+                description = "답변을 입력해주세요.<br>" +
+                        "답변은 최대 250자입니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "403",
+                description = "권한이 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 문의를 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "409",
+                description = "이미 답변 완료된 문의입니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @PatchMapping("/{inquiryId}")
     fun answerInquiry(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @PathVariable inquiryId: Long,
+        @Parameter(description = "(Long) 문의 Id", example = "1") @PathVariable inquiryId: Long,
         @RequestBody @Valid inquiryAnswerReq: InquiryAnswerReq
     ): BaseResponse<Unit> {
         return BaseResponse(inquiryService.answerInquiry(userAccount.getUser(), inquiryId, inquiryAnswerReq))
     }
 
-    // 문의하기 답변 등록
+    // 문의하기 삭제
+    @Operation(summary = "문의하기 삭제(박서연)", description = "문의내역을 삭제한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "403",
+                description = "권한이 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 문의를 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @DeleteMapping("/{inquiryId}")
     fun deleteInquiry(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @PathVariable inquiryId: Long
+        @Parameter(description = "(Long) 문의 Id", example = "1") @PathVariable inquiryId: Long
     ): BaseResponse<Unit> {
         return BaseResponse(inquiryService.deleteInquiry(userAccount.getUser(), inquiryId))
     }

src/main/kotlin/com/psr/psr/inquiry/dto/InquiryAnswerReq.kt

@@ -1,9 +1,11 @@
 package com.psr.psr.inquiry.dto
 
+import io.swagger.v3.oas.annotations.media.Schema
 import jakarta.validation.constraints.NotBlank
 import jakarta.validation.constraints.Size
 
 data class InquiryAnswerReq (
+    @Schema(description = "답변", example = "답변 내용")
     @field:NotBlank(message = "답변을 입력해주세요.")
     @field:Size(max = 250, message = "답변은 최대 250자입니다.")
     val answer: String

src/main/kotlin/com/psr/psr/inquiry/dto/InquiryRes.kt

@@ -2,12 +2,20 @@ package com.psr.psr.inquiry.dto
 
 import com.fasterxml.jackson.annotation.JsonInclude
 import com.psr.psr.inquiry.entity.Inquiry
+import io.swagger.v3.oas.annotations.media.Schema
 
 data class InquiryRes (
+    @Schema(description = "문의 Id", example = "1")
     val inquiryId: Long,
+
+    @Schema(description = "문의 제목", example = "문의 제목")
     val title: String,
+
+    @Schema(description = "문의 내용", example = "문의 내용")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     val content: String?,
+
+    @Schema(description = "문의 답변", example = "문의 답변")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     val answer: String?
 ){

src/main/kotlin/com/psr/psr/notification/controller/NotificationController.kt

@@ -4,8 +4,14 @@ import com.psr.psr.global.dto.BaseResponse
 import com.psr.psr.global.jwt.UserAccount
 import com.psr.psr.notification.dto.NotificationListRes
 import com.psr.psr.notification.service.NotificationService
+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.security.SecurityRequirement
 import io.swagger.v3.oas.annotations.tags.Tag
+import org.springdoc.core.annotations.ParameterObject
 import org.springframework.data.domain.Page
 import org.springframework.data.domain.Pageable
 import org.springframework.data.web.PageableDefault
@@ -22,10 +28,15 @@ class NotificationController(
     private val notificationService: NotificationService
 ) {
     // 알림 목록 조회
+    @Operation(summary = "알림 목록 조회(박서연)", description = "알림 목록을 조회한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다.")]
+    )
     @GetMapping
     fun getNotiList(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @PageableDefault(size = 8) pageable: Pageable  // 8일치 알림
+        @ParameterObject @PageableDefault(size = 8) pageable: Pageable  // 8일치 알림
     ): BaseResponse<Page<NotificationListRes>> {
         return BaseResponse(notificationService.getNotiList(userAccount.getUser(), pageable))
     }

src/main/kotlin/com/psr/psr/notification/dto/NotiList.kt

@@ -1,8 +1,11 @@
 package com.psr.psr.notification.dto
 
 import com.querydsl.core.annotations.QueryProjection
+import io.swagger.v3.oas.annotations.media.Schema
 
 data class NotiList @QueryProjection constructor(
+    @Schema(description = "알림 제목", example = "알림 제목")
     val title: String,
+    @Schema(description = "알림 내용", example = "알림 내용")
     val content: String
 )

src/main/kotlin/com/psr/psr/notification/dto/NotificationListRes.kt

@@ -1,8 +1,10 @@
 package com.psr.psr.notification.dto
 
 import com.querydsl.core.annotations.QueryProjection
+import io.swagger.v3.oas.annotations.media.Schema
 
 data class NotificationListRes @QueryProjection constructor(
+    @Schema(description = "알림 일자", example = "2023-01-01")
     val date: String,
     val notiList: List<NotiList>
 )

src/main/kotlin/com/psr/psr/order/controller/OrderController.kt

@@ -11,9 +11,18 @@ import com.psr.psr.order.dto.OrderListRes
 import com.psr.psr.order.dto.OrderReq
 import com.psr.psr.order.dto.OrderRes
 import com.psr.psr.order.service.OrderService
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.enums.ParameterIn
+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.security.SecurityRequirement
 import io.swagger.v3.oas.annotations.tags.Tag
 import jakarta.validation.Valid
+import org.springdoc.core.annotations.ParameterObject
 import org.springframework.data.domain.Page
 import org.springframework.data.domain.Pageable
 import org.springframework.data.domain.Sort
@@ -29,6 +38,27 @@ class OrderController(
     private val orderService: OrderService
 ) {
     // 요청하기
+    @Operation(summary = "요청하기(박서연)", description = "상품에 대한 요청을 한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "400",
+                description = "이름을 입력해주세요.<br>" +
+                        "이름은 최대 100자입니다.<br>" +
+                        "문의사항을 입력해주세요.<br>" +
+                        "문의사항은 최대 250자입니다.<br>" +
+                        "요청 상세설명을 입력해주세요.<br>" +
+                        "요청 상세설명은 최대 250자입니다.<br>" +
+                        "상품ID를 입력해주세요.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 상품을 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @PostMapping
     fun makeOrder(
         @AuthenticationPrincipal userAccount: UserAccount,
@@ -41,21 +71,59 @@ class OrderController(
     }
 
     // 요청 상세 조회
+    @Operation(summary = "요청 상세 조회(박서연)", description = "요청을 상세조회 한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "403",
+                description = "권한이 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 요청을 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @GetMapping("/{orderId}")
     fun getOrderDetail(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @PathVariable orderId: Long
+        @Parameter(description = "(Long) 요청 Id", example = "1") @PathVariable orderId: Long
     ): BaseResponse<OrderRes> {
         return BaseResponse(orderService.getOrderDetail(userAccount.getUser(), orderId))
     }
 
     // 요청 목록 조회
+    @Operation(summary = "요청 목록 조회(박서연)", description = "요청 목록을 조회 한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "400",
+                description = "올바르지 않은 요청 타입입니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "403",
+                description = "권한이 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 요청을 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @GetMapping
     fun getOrderList(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @RequestParam type: String,
-        @RequestParam(required = false) status: String?,
-        @PageableDefault(size = 10, sort = ["id"], direction = Sort.Direction.DESC) pageable: Pageable
+        @Parameter(description = "요청 타입", example = "sell/order") @RequestParam type: String,
+        @Parameter(
+            description = "요청 상태",
+            example = "요청대기/진행중/진행완료/요청취소"
+        ) @RequestParam(required = false) status: String?,
+        @ParameterObject @PageableDefault(size = 10, sort = ["id"], direction = Sort.Direction.DESC) pageable: Pageable
     ): BaseResponse<Page<OrderListRes>> {
         if (type !in listOf(SELL, ORDER)) return BaseResponse(BaseResponseCode.INVALID_ORDER_TYPE)
 
@@ -66,22 +134,76 @@ class OrderController(
     }
 
     // 요청 수정
+    @Operation(summary = "요청 수정(박서연)", description = "요청을 수정한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "400",
+                description = "이름을 입력해주세요.<br>" +
+                        "이름은 최대 100자입니다.<br>" +
+                        "문의사항을 입력해주세요.<br>" +
+                        "문의사항은 최대 250자입니다.<br>" +
+                        "요청 상세설명을 입력해주세요.<br>" +
+                        "요청 상세설명은 최대 250자입니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "403",
+                description = "권한이 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 요청을 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @PatchMapping("/{orderId}")
     fun editOrder(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @PathVariable orderId: Long,
+        @Parameter(description = "(Long) 요청 Id", example = "1") @PathVariable orderId: Long,
         @RequestBody @Valid orderReq: OrderReq
     ): BaseResponse<Unit> {
         if (orderReq.websiteUrl.isNullOrBlank()) orderReq.websiteUrl = null
         return BaseResponse(orderService.editOrder(userAccount.getUser(), orderReq, orderId))
     }
 
     // 요청 상태 수정
+    @Operation(summary = "요청 상태 수정(박서연)", description = "요청 상태를 수정한다.")
+    @ApiResponses(
+        value = [
+            ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+            ApiResponse(
+                responseCode = "400",
+                description = "요청 상태를 입력해주세요.<br>" +
+                        "올바르지 않은 요청 상태입니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "403",
+                description = "권한이 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "해당 요청을 찾을 수 없습니다.",
+                content = arrayOf(Content(schema = Schema(implementation = BaseResponse::class)))
+            )]
+    )
     @PatchMapping("/{orderId}/status")
     fun editOrderStatus(
         @AuthenticationPrincipal userAccount: UserAccount,
-        @PathVariable orderId: Long,
-        @RequestBody status: Map<String, String>
+        @Parameter(description = "(Long) 요청 Id", example = "1") @PathVariable orderId: Long,
+        @io.swagger.v3.oas.annotations.parameters.RequestBody(
+            content = [Content(
+                examples = [ExampleObject(
+                    value = "{" +
+                            "\"status\" : \"진행중\"" +
+                            "}"
+                )], schema = Schema(title = "status", allowableValues = ["진행중", "진행완료", "요청취소"])
+            )]
+        ) @RequestBody status: Map<String, String>
     ): BaseResponse<Unit> {
         status[Constant.Order.STATUS] ?: return BaseResponse(BaseResponseCode.NULL_ORDER_STATUS)
         return BaseResponse(orderService.editOrderStatus(userAccount.getUser(), status[STATUS]!!, orderId))