[Docs] multipart/form-data 요청 형식 문서화

Author: leegwichan

src/main/java/eatda/controller/story/StoryRegisterRequest.java

@@ -1,7 +1,7 @@
 package eatda.controller.story;
 
 public record StoryRegisterRequest(
-        String query,
+        String storeName,
         String storeKakaoId,
         String description
 ) {

src/main/java/eatda/service/story/StoryService.java

@@ -40,7 +40,7 @@ public class StoryService {
     @Transactional
     public StoryRegisterResponse registerStory(StoryRegisterRequest request, MultipartFile imageFile, Long memberId) {
         Member member = memberRepository.getById(memberId);
-        List<StoreSearchResult> searchResponses = mapClient.searchShops(request.query());
+        List<StoreSearchResult> searchResponses = mapClient.searchShops(request.storeName());
         FilteredSearchResult matchedStore = filteredSearchResponse(searchResponses, request.storeKakaoId());
         ImageKey imageKey = imageStorage.upload(new Image(ImageDomain.STORY, imageFile));
 

src/test/java/eatda/document/store/CheerDocumentTest.java

@@ -39,9 +39,25 @@ public class CheerDocumentTest extends BaseDocumentTest {
     @Nested
     class RegisterCheer {
 
+        private static final String REQUEST_DESCRIPTION_MARKDOWN = """
+                - 요청 형식 : multipart/form-data
+                - 요청 field
+                  - `image` : 응원 이미지 (선택, 최대 5MB, 허용 타입 : image/jpg, image/jpeg, image/png
+                  - `request` : 응원 등록 요청 정보 (필수, 허용 타입 : application/json)
+                - request body 예시
+                    ```json
+                    {
+                        "storeKakaoId": "123", // 가게 카카오 ID
+                        "storeName": "농민백암순대 본점", // 가게 이름
+                        "description": "너무 맛있어요! 준환님 추천 맛집!" // 응원 내용
+                    }
+                    ```
+                """;
+
         RestDocsRequest requestDocument = request()
                 .tag(Tag.STORE_API)
                 .summary("응원 등록")
+                .description(REQUEST_DESCRIPTION_MARKDOWN)
                 .requestHeader(
                         headerWithName("Authorization").description("인증 토큰")
                 ).multipartField(

src/test/java/eatda/document/story/StoryDocumentTest.java

@@ -33,17 +33,32 @@ public class StoryDocumentTest extends BaseDocumentTest {
     @Nested
     class RegisterStory {
 
+        private static final String REQUEST_DESCRIPTION_MARKDOWN = """
+                - 요청 형식 : multipart/form-data
+                - 요청 field
+                  - `image` : 스토리 이미지 (필수, 최대 5MB, 허용 타입 : image/jpg, image/jpeg, image/png
+                  - `request` : 스토리 등록 요청 정보 (필수, 허용 타입 : application/json)
+                - request body 예시
+                    ```json
+                    {
+                        "storeKakaoId": "123", // 가게 카카오 ID
+                        "storeName": "농민백암순대 본점", // 가게 이름
+                        "description": "너무 맛있어요! 준환님 추천 맛집!" // 스토리 내용
+                    }
+                    ```
+                """;
+
         RestDocsRequest requestDocument = request()
                 .tag(Tag.STORY_API)
                 .summary("스토리 등록")
-                .description("스토리와 이미지를 multipart/form-data로 등록합니다.")
+                .description(REQUEST_DESCRIPTION_MARKDOWN)
                 .requestHeader(
                         headerWithName(HttpHeaders.AUTHORIZATION).description("액세스 토큰")
                 ).multipartField(
                         partWithName("image").description("스토리 이미지 (필수)"),
                         partWithName("request").description("스토리 등록 요청 정보")
                 ).requestBodyField("request",
-                        fieldWithPath("query").description("스토리 검색 쿼리"),
+                        fieldWithPath("storeName").description("가게 이름"),
                         fieldWithPath("storeKakaoId").description("가게의 카카오 ID"),
                         fieldWithPath("description").description("스토리 내용 (필수)")
                 );

src/test/java/eatda/service/story/StoryServiceTest.java

@@ -45,7 +45,7 @@ class RegisterStory {
                     "곱창집", "http://example.com",
                     "서울 강남구", "서울 강남구", 37.0, 127.0
             );
-            doReturn(List.of(store)).when(mapClient).searchShops(request.query());
+            doReturn(List.of(store)).when(mapClient).searchShops(request.storeName());
 
             var response = storyService.registerStory(request, imageFile, member.getId());
 
@@ -58,7 +58,7 @@ class RegisterStory {
             StoryRegisterRequest request = new StoryRegisterRequest("곱창", "999", "미쳤다 여기");
 
             MultipartFile image = mock(MultipartFile.class);
-            doReturn(Collections.emptyList()).when(mapClient).searchShops(request.query());
+            doReturn(Collections.emptyList()).when(mapClient).searchShops(request.storeName());
 
             assertThatThrownBy(() -> storyService.registerStory(request, image, member.getId()))
                     .isInstanceOf(BusinessException.class)