From 495e69b2d3f794483140bd7d59951c4327122488 Mon Sep 17 00:00:00 2001 From: bbangjae Date: Sun, 19 Oct 2025 18:15:52 +0900 Subject: [PATCH] =?UTF-8?q?docs(store):=20=EA=B0=80=EA=B2=8C=20=EB=8F=84?= =?UTF-8?q?=EB=A9=94=EC=9D=B8=20=EC=BB=A8=ED=8A=B8=EB=A1=A4=EB=9F=AC/DTO?= =?UTF-8?q?=20=EB=AC=B8=EC=84=9C=ED=99=94=20=EC=9E=91=EC=97=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../store/controller/StoreController.java | 24 +++++++++++++++++++ .../tdd/domain/store/dto/StoreRequestDto.java | 13 +++++++--- .../domain/store/dto/StoreResponseDto.java | 24 +++++++++++++++++++ .../domain/store/dto/StoreSimpleInfoDto.java | 5 ++++ 4 files changed, 63 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/sparta/tdd/domain/store/controller/StoreController.java b/src/main/java/com/sparta/tdd/domain/store/controller/StoreController.java index b87d5e24..50a87e6e 100644 --- a/src/main/java/com/sparta/tdd/domain/store/controller/StoreController.java +++ b/src/main/java/com/sparta/tdd/domain/store/controller/StoreController.java @@ -5,6 +5,7 @@ import com.sparta.tdd.domain.store.dto.StoreResponseDto; import com.sparta.tdd.domain.store.enums.StoreCategory; import com.sparta.tdd.domain.store.service.StoreService; +import io.swagger.v3.oas.annotations.Operation; import jakarta.validation.Valid; import java.net.URI; import java.util.UUID; @@ -31,6 +32,10 @@ public class StoreController { private final StoreService storeService; + @Operation( + summary = "가게 검색", + description = "키워드, 카테고리, 페이징 정보로 가게를 검색합니다. 가게의 메뉴 정보도 함께 조회됩니다." + ) @GetMapping public ResponseEntity> searchStores( @RequestParam(required = false) String keyword, @@ -41,6 +46,10 @@ public ResponseEntity> searchStores( return ResponseEntity.ok(responseDto); } + @Operation( + summary = "가게 생성", + description = "새로운 가게를 등록합니다. OWNER, MANAGER, MASTER 권한이 필요합니다." + ) @PreAuthorize("hasAnyRole('OWNER', 'MANAGER', 'MASTER')") @PostMapping public ResponseEntity createStore( @@ -56,12 +65,23 @@ public ResponseEntity createStore( .body(responseDto); } + + @Operation( + summary = "가게 조회", + description = """ + 스토어 ID를 통해 가게를 조회 합니다. + """ + ) @GetMapping("{storeId}") public ResponseEntity getStore(@PathVariable UUID storeId) { StoreResponseDto responseDto = storeService.getStore(storeId); return ResponseEntity.ok(responseDto); } + @Operation( + summary = "가게 상세 조회", + description = "스토어 ID를 통해 가게의 상세 정보를 조회합니다." + ) @PreAuthorize("hasAnyRole('OWNER', 'MANAGER', 'MASTER')") @PatchMapping("{storeId}") public ResponseEntity updateStore( @@ -73,6 +93,10 @@ public ResponseEntity updateStore( return ResponseEntity.ok().build(); } + @Operation( + summary = "가게 정보 수정", + description = "가게 정보를 수정합니다. OWNER, MANAGER, MASTER 권한이 필요합니다." + ) @PreAuthorize("hasAnyRole('OWNER', 'MANAGER', 'MASTER')") @DeleteMapping("{storeId}") public ResponseEntity deleteStore( diff --git a/src/main/java/com/sparta/tdd/domain/store/dto/StoreRequestDto.java b/src/main/java/com/sparta/tdd/domain/store/dto/StoreRequestDto.java index a75dc938..68ccd6c6 100644 --- a/src/main/java/com/sparta/tdd/domain/store/dto/StoreRequestDto.java +++ b/src/main/java/com/sparta/tdd/domain/store/dto/StoreRequestDto.java @@ -3,6 +3,7 @@ import com.sparta.tdd.domain.store.entity.Store; import com.sparta.tdd.domain.store.enums.StoreCategory; import com.sparta.tdd.domain.user.entity.User; +import io.swagger.v3.oas.annotations.media.Schema; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; import jakarta.validation.constraints.Pattern; @@ -10,19 +11,25 @@ import lombok.Builder; @Builder +@Schema(description = "가게 등록 요청DTO") public record StoreRequestDto( - @NotBlank + @NotBlank(message = "가게 이름은 필수입니다.") + @Schema(description = "가게 이름", example = "홍콩반점") String name, - @NotNull + @NotNull(message = "상점 카테고리는 필수입니다.") + @Schema(description = "상점 카테고리", implementation = StoreCategory.class) StoreCategory category, @Size(max = 255) + @Schema(description = "가게 설명 (최대 255자)", example = "정통 중화요리를 판매하는 홍콩반점입니다.") String description, @Pattern(regexp = "^(http|https)://.*$") - String imageUrl) { + @Schema(description = "상점 이미지 URL", example = "https://example.com/image.jpg") + String imageUrl +) { public Store toEntity(User user) { return Store.builder() diff --git a/src/main/java/com/sparta/tdd/domain/store/dto/StoreResponseDto.java b/src/main/java/com/sparta/tdd/domain/store/dto/StoreResponseDto.java index bbc55eaf..3d1f49fe 100644 --- a/src/main/java/com/sparta/tdd/domain/store/dto/StoreResponseDto.java +++ b/src/main/java/com/sparta/tdd/domain/store/dto/StoreResponseDto.java @@ -10,6 +10,8 @@ import com.sparta.tdd.domain.store.entity.QStore; import com.sparta.tdd.domain.store.entity.Store; import com.sparta.tdd.domain.store.enums.StoreCategory; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Schema; import java.math.BigDecimal; import java.util.ArrayList; import java.util.List; @@ -17,16 +19,38 @@ import lombok.Builder; @Builder +@Schema(description = "가게 조회 응답 DTO") public record StoreResponseDto( + + @Schema(description = "가게 ID", example = "4f1ed1a0-e7dc-4f7d-a806-412e0e07bfbe") UUID id, + + @Schema(description = "가게 이름", example = "홍콩반점") String name, + + @Schema(description = "점주 이름", example = "TDD") String ownerName, + + @Schema(description = "상점 카테고리", implementation = StoreCategory.class) StoreCategory category, + + @Schema(description = "가게 설명", example = "정통 중화요리를 판매하는 홍콩반점입니다.") String description, + + @Schema(description = "상점 이미지 URL", example = "https://example.com/images/store1.jpg") String imageUrl, + + @Schema(description = "평균 평점", example = "4.5") BigDecimal avgRating, + + @Schema(description = "리뷰 개수", example = "128") Integer reviewCount, + + @Schema(description = "총 주문 수", example = "3456") Long orderCount, + + @ArraySchema(schema = @Schema(implementation = MenuWithStoreResponseDto.class), + arraySchema = @Schema(description = "가게에 등록된 메뉴 목록")) List menus ) { diff --git a/src/main/java/com/sparta/tdd/domain/store/dto/StoreSimpleInfoDto.java b/src/main/java/com/sparta/tdd/domain/store/dto/StoreSimpleInfoDto.java index 08564d53..0a52dd03 100644 --- a/src/main/java/com/sparta/tdd/domain/store/dto/StoreSimpleInfoDto.java +++ b/src/main/java/com/sparta/tdd/domain/store/dto/StoreSimpleInfoDto.java @@ -1,10 +1,15 @@ package com.sparta.tdd.domain.store.dto; import com.sparta.tdd.domain.store.entity.Store; +import io.swagger.v3.oas.annotations.media.Schema; import java.util.UUID; public record StoreSimpleInfoDto( + + @Schema(description = "가게 ID", example = "4f1ed1a0-e7dc-4f7d-a806-412e0e07bfbe") UUID id, + + @Schema(description = "가게 이름", example = "홍콩반점") String storeName ) {