Merge pull request #87 from team-nabi/NABI-374--junhyuk--chore--api-spec

NABI-374 : API 명세 정리

src/main/java/org/prgrms/nabimarketbe/domain/card/api/CardController.java

@@ -1,8 +1,9 @@
 package org.prgrms.nabimarketbe.domain.card.api;
 
+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.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.prgrms.nabimarketbe.domain.card.dto.request.CardCreateRequestDTO;
 import org.prgrms.nabimarketbe.domain.card.dto.request.CardStatusUpdateRequestDTO;
@@ -19,7 +20,6 @@
 import org.prgrms.nabimarketbe.domain.card.service.CardService;
 import org.prgrms.nabimarketbe.domain.category.entity.CategoryEnum;
 import org.prgrms.nabimarketbe.domain.item.entity.PriceRange;
-import org.prgrms.nabimarketbe.global.util.KeyGenerator;
 import org.prgrms.nabimarketbe.global.util.OrderCondition;
 import org.prgrms.nabimarketbe.global.util.ResponseFactory;
 import org.prgrms.nabimarketbe.global.util.model.CommonResult;
@@ -38,31 +38,32 @@
 
 import java.util.List;
 
+@Tag(name = "카드", description = "카드 관련 API 입니다.")
 @RestController
 @RequestMapping("/api/v1/cards")
 @RequiredArgsConstructor
 public class CardController {
     private final CardService cardService;
 
-    @Parameter(
-        name = "Authorization",
-        description = "로그인 성공 후 AccessToken",
-        required = true,
-        schema = @Schema(type = "string"),
-        in = ParameterIn.HEADER)
+    @Operation(summary = "카드 등록", description = "카드를 등록합니다.")
     @PostMapping
     public ResponseEntity<SingleResult<CardResponseDTO<CardCreateResponseDTO>>> createCard(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader("Authorization") String token,
+        @Parameter(description = "카드 등록 요청값", required = true)
         @RequestBody CardCreateRequestDTO cardCreateRequestDTO
     ) {
         CardResponseDTO<CardCreateResponseDTO> card = cardService.createCard(token, cardCreateRequestDTO);
 
         return ResponseEntity.ok(ResponseFactory.getSingleResult(card));
     }
 
+    @Operation(summary = "카드 단건 조회", description = "카드 한 건을 조회합니다.")
     @GetMapping("/{cardId}")
     public ResponseEntity<SingleResult<CardUserResponseDTO>> getCardById(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", in = ParameterIn.HEADER)
         @RequestHeader(value = "Authorization", required = false) String token,
+        @Parameter(description = "카드 id(pk)", required = true)
         @PathVariable Long cardId
     ) {
         CardUserResponseDTO cardSingleReadResponseDTO = cardService.getCardById(
@@ -73,13 +74,20 @@ public ResponseEntity<SingleResult<CardUserResponseDTO>> getCardById(
         return ResponseEntity.ok(ResponseFactory.getSingleResult(cardSingleReadResponseDTO));
     }
 
+    @Operation(summary = "카드 목록 조회", description = "카드 목록을 조건에 따라 조회합니다.")
     @GetMapping
     public ResponseEntity<SingleResult<CardPagingResponseDTO>> getCardsByCondition(
+        @Parameter(description = "카테고리")
         @RequestParam(required = false) CategoryEnum category,
+        @Parameter(description = "가격대")
         @RequestParam(required = false) PriceRange priceRange,
+        @Parameter(description = "카드 상태(거래 가능, 예약중, 거래 완료)")
         @RequestParam(required = false) List<CardStatus> status,
+        @Parameter(description = "카드 제목")
         @RequestParam(required = false) String cardTitle,
+        @Parameter(description = "커서 id")
         @RequestParam(required = false) String cursorId,
+        @Parameter(description = "page 크기", required = true)
         @RequestParam Integer size
     ) {
         // TODO: 클라이언트에게 정렬 조건 받도록 추후에 수정하면 더 유연할 듯
@@ -98,9 +106,12 @@ public ResponseEntity<SingleResult<CardPagingResponseDTO>> getCardsByCondition(
         return ResponseEntity.ok(ResponseFactory.getSingleResult(cardListReadPagingResponseDTO));
     }
 
+    @Operation(summary = "제안 가능한 내 카드 리슨트 조회", description = "특정 카드에 제안할 수 있는 내 카드 목록을 조회합니다.")
     @GetMapping("/{cardId}/available-cards")
     public ResponseEntity<SingleResult<CardListResponseDTO<CardSuggestionResponseDTO>>> getSuggestionAvailableCards(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "제안 하고 싶은 상대방의 카드 id(pk)", required = true)
         @PathVariable(name = "cardId") Long targetCardId
     ) {
         CardListResponseDTO<CardSuggestionResponseDTO> cardListResponseDTO
@@ -109,10 +120,14 @@ public ResponseEntity<SingleResult<CardListResponseDTO<CardSuggestionResponseDTO
         return ResponseEntity.ok(ResponseFactory.getSingleResult(cardListResponseDTO));
     }
 
+    @Operation(summary = "카드 조회 수정 api", description = "자신이 등록한 카드의 정보를 수정합니다.")
     @PutMapping("/{cardId}")
     public ResponseEntity<SingleResult<CardResponseDTO<CardUpdateResponseDTO>>> updateCardById(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader("Authorization") String token,
+        @Parameter(description = "자신의 카드 id(pk)", required = true)
         @PathVariable Long cardId,
+        @Parameter(description = "카드 수정 요청값", required = true)
         @RequestBody CardUpdateRequestDTO cardUpdateRequestDTO
     ) {
         CardResponseDTO<CardUpdateResponseDTO> cardResponseDTO = cardService.updateCardById(
@@ -124,10 +139,14 @@ public ResponseEntity<SingleResult<CardResponseDTO<CardUpdateResponseDTO>>> upda
         return ResponseEntity.ok(ResponseFactory.getSingleResult(cardResponseDTO));
     }
 
+    @Operation(summary = "카드에 대한 제안 결정", description = "자신의 카드에 들어온 제안에 대해 결정합니다.")
     @PutMapping("/status/{cardId}")
     public ResponseEntity<CommonResult> updateCardStatusById(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "자신의 카드 id(pk)", required = true)
         @PathVariable Long cardId,
+        @Parameter(description = "카드 제안에 대한 결정 결과값")
         @RequestBody CardStatusUpdateRequestDTO cardStatusUpdateRequestDTO
     ) {
         cardService.updateCardStatusById(
@@ -139,11 +158,16 @@ public ResponseEntity<CommonResult> updateCardStatusById(
         return ResponseEntity.ok(ResponseFactory.getSuccessResult());
     }
 
+    @Operation(summary = "자신의 카드 목록 조회(상태 기반)", description = "카드 상태에 따른 자신의 카드 목록을 조회합니다.")
     @GetMapping("/{status}/my-cards")
     public ResponseEntity<SingleResult<CardPagingResponseDTO>> getMyCardsByStatus(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "카드 상태", required = true)
         @PathVariable CardStatus status,
+        @Parameter(description = "커서 id")
         @RequestParam(required = false) String cursorId,
+        @Parameter(description = "page 크기", required = true)
         @RequestParam Integer size
     ) {
         CardPagingResponseDTO cardListReadPagingResponseDTO = cardService.getMyCardsByStatus(
@@ -156,16 +180,20 @@ public ResponseEntity<SingleResult<CardPagingResponseDTO>> getMyCardsByStatus(
         return ResponseEntity.ok(ResponseFactory.getSingleResult(cardListReadPagingResponseDTO));
     }
 
+    @Operation(summary = "카드 삭제", description = "자신의 카드를 삭제합니다.")
     @DeleteMapping("/{cardId}")
     public ResponseEntity<CommonResult> deleteCardById(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "삭제하고자 하는 자신의 카드 id(pk)", required = true)
         @PathVariable Long cardId
     ) {
         cardService.deleteCardById(token, cardId);
 
         return ResponseEntity.ok(ResponseFactory.getSuccessResult());
     }
 
+    @Operation(summary = "인기 상품 목록 조회", description = "메인 베너에 띄우는 인기 상품 목록을 조회합니다.")
     @GetMapping("/popular")
     public ResponseEntity<SingleResult<CardListResponseDTO<CardFamousResponseDTO>>> getCardsByPopularity() {
         CardListResponseDTO<CardFamousResponseDTO> cardList = cardService.getCardsByPopularity();

src/main/java/org/prgrms/nabimarketbe/domain/card/dto/request/CardCreateRequestDTO.java

@@ -7,6 +7,7 @@
 import javax.validation.constraints.NotNull;
 import javax.validation.constraints.Size;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.prgrms.nabimarketbe.domain.card.entity.Card;
 import org.prgrms.nabimarketbe.domain.card.entity.TradeType;
 import org.prgrms.nabimarketbe.domain.cardimage.dto.request.CardImageCreateRequestDTO;
@@ -17,38 +18,49 @@
 import org.prgrms.nabimarketbe.domain.user.entity.User;
 import org.prgrms.nabimarketbe.global.annotation.ValidEnum;
 
+@Schema(title = "카드 등록 요청값 body data", description = "카드 등록 요청에 필요한 값들입니다.")
 public record CardCreateRequestDTO(
+    @Schema(title = "카드 제목", description = "카드 제목입니다.", example = "나비 카드 교환 원해요~")
     @NotBlank(message = "공백을 허용하지 않습니다.")
     @Size(max = 30)
     String cardTitle,
 
+    @Schema(title = "썸네일 링크", description = "썸네일 이미지 링크입니다.", example = "https://xxx.amazonaws.com/xxx.png")
     @NotBlank(message = "공백을 허용하지 않습니다.")
     String thumbnail,
 
+    @Schema(title = "아이템 이름", description = "아이템 이름입니다.", example = "나비 카드")
     @NotBlank(message = "공백을 허용하지 않습니다.")
     @Size(max = 30)
     String itemName,
 
+    @Schema(title = "가격대", description = "상품의 가격대입니다.", example = "PRICE_RANGE_ONE")
     @ValidEnum(enumClass = PriceRange.class, message = "유효하지 않은 가격대입니다.")
     PriceRange priceRange,
 
+    @Schema(title = "거래 방식", description = "카드의 거래 방식을 의미합니다.", example = "DIRECT_DEALING")
     @ValidEnum(enumClass = TradeType.class, message = "유효하지 않은 거래 방식입니다.")
     TradeType tradeType,
 
+    @Schema(title = "거래 지역", description = "거래 하고자 하는 지역을 의미합니다.", example = "서울시 노원구")
     @NotNull
     @Size(max = 30)
     String tradeArea,
 
+    @Schema(title = "카드 카테고리", description = "카드의 카테고리를 의미합니다.", example = "SHOES")
     @ValidEnum(enumClass = CategoryEnum.class, message = "유효하지 않은 카테고리입니다.")
     CategoryEnum category,
 
+    @Schema(title = "카드 찔러보기 유무", description = "카드의 찔러보기 허용 여부를 의미합니다.", example = "true")
     @NotNull(message = "비울 수 없는 값입니다.")
     Boolean pokeAvailable,
 
+    @Schema(title = "카드 본문 내용", description = "카드의 본문 내용을 의미합니다.", example = "나비 카드 교환원합니다. 상태 좋아요~!")
     @NotBlank(message = "공백을 허용하지 않습니다.")
     @Size(max = 255)
     String content,
 
+    @Schema(title = "카드 이미지 링크 목록", description = "카드의 이미지 링크 목록")
     @Nullable
     List<CardImageCreateRequestDTO> images
 ) {

src/main/java/org/prgrms/nabimarketbe/domain/chatroom/api/CharRoomController.java

@@ -1,5 +1,9 @@
 package org.prgrms.nabimarketbe.domain.chatroom.api;
 
+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.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.prgrms.nabimarketbe.domain.chatroom.dto.response.list.ChatRoomListWrapper;
 import org.prgrms.nabimarketbe.domain.chatroom.dto.response.single.ChatRoomInfoWrapper;
@@ -14,26 +18,34 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "채팅방", description = "채팅방 생성 및 접근 관련 API 입니다.")
 @RestController
 @RequestMapping("/api/v1/chats")
 @RequiredArgsConstructor
 public class CharRoomController {
     private final ChatRoomService chatRoomService;
 
+    @Operation(summary = "채팅방 단건 조회", description = "채팅방 단건 조회를 할 수 있습니다.")
     @GetMapping("/{chatRoomId}")
     public ResponseEntity<SingleResult<ChatRoomInfoWrapper>> getChatRoomById(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "채팅방 접근을 위한 id(pk)", required = true)
         @PathVariable Long chatRoomId
     ) {
         ChatRoomInfoWrapper charRoomInfo = chatRoomService.getChatRoomById(token, chatRoomId);
 
         return ResponseEntity.ok(ResponseFactory.getSingleResult(charRoomInfo));
     }
 
+    @Operation(summary = "채팅방 목록 조회", description = "개설된 채팅방 목록 조회를 할 수 있습니다.")
     @GetMapping
     public ResponseEntity<SingleResult<ChatRoomListWrapper>> getChatRooms(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "채팅방 목록 페이징을 위한 cursor id")
         @RequestParam(required = false) String cursorId,
+        @Parameter(description = "채팅방 목록 페이지 크기", required = true)
         @RequestParam Integer size
     ) {
         ChatRoomListWrapper chatRoomList = chatRoomService.getChatRooms(token, cursorId, size);

src/main/java/org/prgrms/nabimarketbe/domain/completeRequest/api/CompleteRequestController.java

@@ -1,5 +1,9 @@
 package org.prgrms.nabimarketbe.domain.completeRequest.api;
 
+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.tags.Tag;
 import org.prgrms.nabimarketbe.domain.completeRequest.dto.request.CompleteRequestDTO;
 import org.prgrms.nabimarketbe.domain.completeRequest.dto.request.CompleteRequestUpdateDTO;
 import org.prgrms.nabimarketbe.domain.completeRequest.dto.response.CompleteRequestResponseDTO;
@@ -23,15 +27,19 @@
 
 import lombok.RequiredArgsConstructor;
 
+@Tag(name = "거래 성사", description = "거래 성사 요청 관련 API 입니다.")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/complete-requests")
 public class CompleteRequestController {
     private final CompleteRequestService completeRequestService;
 
+    @Operation(summary = "거래 성사 요청", description = "거래 성사 요청을 보냅니다.")
     @PostMapping
     public ResponseEntity<SingleResult<CompleteRequestResponseDTO>> createCompleteRequest(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "거래 성사 요청값", required = true)
         @RequestBody CompleteRequestDTO completeRequestDTO
     ) {
         CompleteRequestResponseDTO completeRequestResponseDTO = completeRequestService.createCompleteRequest(
@@ -42,17 +50,25 @@ public ResponseEntity<SingleResult<CompleteRequestResponseDTO>> createCompleteRe
         return ResponseEntity.ok(ResponseFactory.getSingleResult(completeRequestResponseDTO));
     }
 
+    @Operation(summary = "거래 성사 히스토리", description = "성사된 거래의 목록을 조회합니다.")
     @GetMapping
-    public ResponseEntity<SingleResult<HistoryListReadLimitResponseDTO>> getHistoryBySize(@RequestParam Integer size) {
+    public ResponseEntity<SingleResult<HistoryListReadLimitResponseDTO>> getHistoryBySize(
+        @Parameter(description = "페이지 size", required = true)
+        @RequestParam Integer size
+    ) {
         HistoryListReadLimitResponseDTO historyListReadLimitResponseDTO = completeRequestService.getHistoryBySize(size);
 
         return ResponseEntity.ok(ResponseFactory.getSingleResult(historyListReadLimitResponseDTO));
     }
 
+    @Operation(summary = "유저별 거래 성사 내역 조회", description = "유저 별 성사된 거래의 목록을 조회합니다.")
     @GetMapping("/user")
     public ResponseEntity<SingleResult<HistoryListReadPagingResponseDTO>> getHistoryByUser(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader("Authorization") String token,
+        @Parameter(description = "커서 id")
         @RequestParam(required = false) String cursorId,
+        @Parameter(description = "페이지 size", required = true)
         @RequestParam Integer size
     ){
         HistoryListReadPagingResponseDTO historyByUser = completeRequestService.getHistoryByUser(
@@ -64,9 +80,13 @@ public ResponseEntity<SingleResult<HistoryListReadPagingResponseDTO>> getHistory
         return ResponseEntity.ok(ResponseFactory.getSingleResult(historyByUser));
     }
 
+
+    @Operation(summary = "거래 성사 요청 단건 조회", description = "거래 성사 요청 단건 조회합니다.")
     @GetMapping("/{completeRequestId}")
     public ResponseEntity<SingleResult<CompleteRequestInfoDTO>> getCompleteRequestById(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "거래 성사 요청 id(pk)", required = true)
         @PathVariable Long completeRequestId
     ) {
         CompleteRequestInfoDTO completeRequestById = completeRequestService.getCompleteRequestById(
@@ -77,9 +97,12 @@ public ResponseEntity<SingleResult<CompleteRequestInfoDTO>> getCompleteRequestBy
         return ResponseEntity.ok((ResponseFactory.getSingleResult(completeRequestById)));
     }
 
+    @Operation(summary = "거래 성사 요청 응답", description = "들어온 거래 성사 요청에 대해 응답합니다.")
     @PutMapping("/confirm")
     public ResponseEntity<SingleResult<CompleteRequestResponseDTO>> updateCompleteRequestStatus(
+        @Parameter(name = "Authorization", description = "로그인 성공 후 AccessToken", required = true, in = ParameterIn.HEADER)
         @RequestHeader(name = "Authorization") String token,
+        @Parameter(description = "거래 성사 요청에 대한 응답", required = true)
         @RequestBody CompleteRequestUpdateDTO completeRequestUpdateDTO
     ) {
         CompleteRequestResponseDTO completeRequestDTO = completeRequestService.updateCompleteRequestStatus(