docs(store): 가게 도메인 컨트롤러/DTO 문서화 작업

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<Page<StoreResponseDto>> searchStores(
         @RequestParam(required = false) String keyword,
@@ -41,6 +46,10 @@ public ResponseEntity<Page<StoreResponseDto>> searchStores(
         return ResponseEntity.ok(responseDto);
     }
 
+    @Operation(
+        summary = "가게 생성",
+        description = "새로운 가게를 등록합니다. OWNER, MANAGER, MASTER 권한이 필요합니다."
+    )
     @PreAuthorize("hasAnyRole('OWNER', 'MANAGER', 'MASTER')")
     @PostMapping
     public ResponseEntity<StoreResponseDto> createStore(
@@ -56,12 +65,23 @@ public ResponseEntity<StoreResponseDto> createStore(
             .body(responseDto);
     }
 
+
+    @Operation(
+        summary = "가게 조회",
+        description = """
+            스토어 ID를 통해 가게를 조회 합니다.
+            """
+    )
     @GetMapping("{storeId}")
     public ResponseEntity<StoreResponseDto> 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<Void> updateStore(
@@ -73,6 +93,10 @@ public ResponseEntity<Void> updateStore(
         return ResponseEntity.ok().build();
     }
 
+    @Operation(
+        summary = "가게 정보 수정",
+        description = "가게 정보를 수정합니다. OWNER, MANAGER, MASTER 권한이 필요합니다."
+    )
     @PreAuthorize("hasAnyRole('OWNER', 'MANAGER', 'MASTER')")
     @DeleteMapping("{storeId}")
     public ResponseEntity<Void> deleteStore(

src/main/java/com/sparta/tdd/domain/store/dto/StoreRequestDto.java

@@ -3,26 +3,33 @@
 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;
 import jakarta.validation.constraints.Size;
 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()

src/main/java/com/sparta/tdd/domain/store/dto/StoreResponseDto.java

@@ -10,23 +10,47 @@
 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;
 import java.util.UUID;
 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<MenuWithStoreResponseDto> menus
 ) {
 

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
 ) {