Merge pull request #122 from prgrms-be-devcourse/docs/api-docs

docs: API 문서화
prgrms-be-devcourse · Sep 22, 2023 · 98e7520 · 98e7520
2 parents c539360 + 5a62ecd
commit 98e7520
Show file tree

Hide file tree

Showing 10 changed files with 609 additions and 76 deletions.
diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc
diff --git a/src/main/java/com/prgrms/nabmart/global/config/WebSecurityConfig.java b/src/main/java/com/prgrms/nabmart/global/config/WebSecurityConfig.java
@@ -71,7 +71,8 @@ private RequestMatcher[] requestPermitAll() {
             antMatcher(POST, "/api/v1/riders/**"),
             antMatcher(GET, "/api/v1/categories/**"),
             antMatcher(GET, "/api/v1/items/**"),
-            antMatcher(GET, "/api/v1/events/**"));
+            antMatcher(GET, "/api/v1/events/**"),
+            antMatcher(GET, "/docs/**"));
         return requestMatchers.toArray(RequestMatcher[]::new);
     }
 

diff --git a/src/test/java/com/prgrms/nabmart/base/BaseControllerTest.java b/src/test/java/com/prgrms/nabmart/base/BaseControllerTest.java
@@ -1,5 +1,9 @@
 package com.prgrms.nabmart.base;
 
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
+import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
+import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
 import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -124,6 +128,11 @@ void mockMvcSetUp(
         this.mockMvc = MockMvcBuilders.webAppContextSetup(context)
             .alwaysDo(print())
             .alwaysDo(restDocs)
+            .alwaysDo(
+                document("{method-name}",
+                    preprocessRequest(prettyPrint()),
+                    preprocessResponse(prettyPrint()))
+            )
             .addFilter(new CharacterEncodingFilter("UTF-8", true))
             .addFilter(new JwtAuthenticationFilter(jwtAuthenticationProvider))
             .apply(MockMvcRestDocumentation.documentationConfiguration(provider))

diff --git a/src/test/java/com/prgrms/nabmart/domain/cart/controller/CartItemControllerTest.java b/src/test/java/com/prgrms/nabmart/domain/cart/controller/CartItemControllerTest.java
@@ -130,7 +130,7 @@ class FindCartItemsAPITest {
 
             @Test
             @DisplayName("성공")
-            void findCartItemsByUserId() throws Exception {
+            void findCartItems() throws Exception {
                 // given
                 Long userId = 1L;
                 Long cartId = 1L;

diff --git a/src/test/java/com/prgrms/nabmart/domain/category/controller/CategoryControllerTest.java b/src/test/java/com/prgrms/nabmart/domain/category/controller/CategoryControllerTest.java
@@ -4,10 +4,7 @@
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
-import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
-import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
 import static org.springframework.restdocs.payload.JsonFieldType.ARRAY;
 import static org.springframework.restdocs.payload.JsonFieldType.NUMBER;
 import static org.springframework.restdocs.payload.JsonFieldType.STRING;
@@ -53,9 +50,7 @@ public void saveMainCategory() throws Exception {
                 .andExpect(status().isCreated())
                 .andExpect(header().string("Location", "/api/v1/main-categories/1"))
                 .andDo(print())
-                .andDo(document(
-                    "Save MainCategory",
-                    requestFields(
+                .andDo(restDocs.document(requestFields(
                         fieldWithPath("name").type(STRING)
                             .description("대카테고리명")
                     )
@@ -85,9 +80,7 @@ public void saveSubCategory() throws Exception {
                 .andExpect(status().isCreated())
                 .andExpect(header().string("Location", "/api/v1/sub-categories/1"))
                 .andDo(print())
-                .andDo(document(
-                    "Save SubCategory",
-                    requestFields(
+                .andDo(restDocs.document(requestFields(
                         fieldWithPath("mainCategoryId").type(NUMBER)
                             .description("대카테고리 Id"),
                         fieldWithPath("name").type(STRING)
@@ -115,9 +108,7 @@ public void findAllMainCategories() throws Exception {
                     .contentType(MediaType.APPLICATION_JSON))
                 .andExpect(status().isOk())
                 .andDo(print())
-                .andDo(document(
-                    "Find All MainCategories",
-                    responseFields(
+                .andDo(restDocs.document(responseFields(
                         fieldWithPath("mainCategoryNames").type(ARRAY)
                             .description("대카테고리 리스트")
                     )
@@ -131,7 +122,7 @@ class findSubCategoriesApi {
 
         @Test
         @DisplayName("성공")
-        public void findSubCategories() throws Exception {
+        public void findAllSubCategories() throws Exception {
             // Given
             Long mainCategoryId = 1L;
             FindSubCategoriesResponse subCategoriesResponse = CategoryFixture.findSubCategoriesResponse();
@@ -142,12 +133,7 @@ public void findSubCategories() throws Exception {
             mockMvc.perform(get("/api/v1/categories/{mainCategoryId}", mainCategoryId)
                     .contentType(MediaType.APPLICATION_JSON))
                 .andExpect(status().isOk())
-                .andDo(document(
-                    "Find SubCategories By MainCategory",
-                    preprocessRequest(
-                        prettyPrint()
-                    ),
-                    pathParameters(
+                .andDo(restDocs.document(pathParameters(
                         parameterWithName("mainCategoryId").description("대카테고리 Id")
                     ),
                     responseFields(

diff --git a/src/test/java/com/prgrms/nabmart/domain/coupon/controller/CouponControllerTest.java b/src/test/java/com/prgrms/nabmart/domain/coupon/controller/CouponControllerTest.java
@@ -2,9 +2,6 @@
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.when;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
-import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
-import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
 import static org.springframework.restdocs.payload.JsonFieldType.ARRAY;
 import static org.springframework.restdocs.payload.JsonFieldType.NUMBER;
 import static org.springframework.restdocs.payload.JsonFieldType.STRING;
@@ -59,20 +56,16 @@ void RegisterCoupon() throws Exception {
                 .andExpect(status().isCreated())
                 .andExpect(header().string("Location", "/api/v1/coupons/1"))
                 .andDo(print())
-                .andDo(document("Register coupon",
-                        preprocessRequest(
-                            prettyPrint()
-                        ),
-                        requestFields(
-                            fieldWithPath("name").type(STRING).description("couponName"),
-                            fieldWithPath("discount").type(NUMBER)
-                                .description("discount"),
-                            fieldWithPath("description").type(STRING)
-                                .description("couponDescription"),
-                            fieldWithPath("minOrderPrice").type(NUMBER)
-                                .description("minOrderPrice"),
-                            fieldWithPath("endAt").type(STRING)
-                                .description("endAt (yyyy-MM-dd)"))
+                .andDo(restDocs.document(requestFields(
+                        fieldWithPath("name").type(STRING).description("couponName"),
+                        fieldWithPath("discount").type(NUMBER)
+                            .description("discount"),
+                        fieldWithPath("description").type(STRING)
+                            .description("couponDescription"),
+                        fieldWithPath("minOrderPrice").type(NUMBER)
+                            .description("minOrderPrice"),
+                        fieldWithPath("endAt").type(STRING)
+                            .description("endAt (yyyy-MM-dd)"))
                     )
                 );
         }
@@ -103,14 +96,10 @@ void RegisterUserCoupon() throws Exception {
                 .andExpect(status().isCreated())
                 .andExpect(header().string("Location", "/api/v1/my-coupons/1"))
                 .andDo(print())
-                .andDo(document("Register userCoupon",
-                        preprocessRequest(
-                            prettyPrint()
-                        ),
-                        requestFields(
-                            fieldWithPath("userId").type(NUMBER).description("userId"),
-                            fieldWithPath("couponId").type(NUMBER)
-                                .description("couponId"))
+                .andDo(restDocs.document(requestFields(
+                        fieldWithPath("userId").type(NUMBER).description("userId"),
+                        fieldWithPath("couponId").type(NUMBER)
+                            .description("couponId"))
                     )
                 );
         }

diff --git a/src/test/java/com/prgrms/nabmart/domain/event/controller/EventControllerTest.java b/src/test/java/com/prgrms/nabmart/domain/event/controller/EventControllerTest.java
@@ -2,9 +2,10 @@
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.BDDMockito.given;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@@ -48,8 +49,7 @@ public void registerEvent() throws Exception {
 
             // Then
             resultActions.andExpect(status().isCreated())
-                .andDo(document("Register Event"
-                ));
+                .andDo(restDocs.document());
         }
     }
 
@@ -74,7 +74,7 @@ public void findEvents() throws Exception {
 
             // Then
             resultActions.andExpect(status().isOk())
-                .andDo(document("Find Events",
+                .andDo(restDocs.document(
                     responseFields(
                         fieldWithPath("events[].eventId").type(JsonFieldType.NUMBER)
                             .description("이벤트 ID"),
@@ -118,7 +118,7 @@ public void findEventDetail() throws Exception {
 
             // Then
             resultActions.andExpect(status().isOk())
-                .andDo(document("Find Event Detail",
+                .andDo(restDocs.document(
                         responseFields(
                             fieldWithPath("event.eventId").type(JsonFieldType.NUMBER)
                                 .description("이벤트 ID"),
@@ -167,8 +167,7 @@ public void registerEventItems() throws Exception {
 
             // Then
             resultActions.andExpect(status().isCreated())
-                .andDo(document("Register Event Items"
-                ));
+                .andDo(restDocs.document());
         }
     }
 }
diff --git a/src/test/java/com/prgrms/nabmart/domain/item/controller/ItemControllerTest.java b/src/test/java/com/prgrms/nabmart/domain/item/controller/ItemControllerTest.java
@@ -3,7 +3,6 @@
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.BDDMockito.given;
 import static org.mockito.Mockito.when;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.delete;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.patch;
@@ -120,7 +119,7 @@ public void findItemDetail() throws Exception {
 
             // Then
             resultActions.andExpect(status().isOk())
-                .andDo(document("Find Item Detail",
+                .andDo(restDocs.document(
                     pathParameters(
                         parameterWithName("itemId").description("상품 ID")
                     ),
@@ -173,7 +172,7 @@ public void findNewItems() throws Exception {
 
             // Then
             resultActions.andExpect(status().isOk())
-                .andDo(document("Find New Items",
+                .andDo(restDocs.document(
                     queryParameters(
                         parameterWithName("lastItemId").description("마지막에 조회한 아이템의 특성값"),
                         parameterWithName("lastItemId").description("마지막에 조회한 아이템 ID"),
@@ -225,7 +224,7 @@ public void findHotItems() throws Exception {
 
             // Then
             resultActions.andExpect(status().isOk())
-                .andDo(document("Find Hot Items",
+                .andDo(restDocs.document(
                     queryParameters(
                         parameterWithName("lastItemId").description("마지막에 조회한 아이템의 특성값"),
                         parameterWithName("lastItemId").description("마지막에 조회한 아이템 ID"),
@@ -273,8 +272,7 @@ public void updateItem() throws Exception {
 
             // Then
             resultActions.andExpect(status().isNoContent())
-                .andDo(document(
-                    "Update Item",
+                .andDo(restDocs.document(
                     requestFields(
                         fieldWithPath("name").type(STRING)
                             .description("상품명"),
@@ -317,8 +315,7 @@ public void registerItem() throws Exception {
 
             // Then
             resultActions.andExpect(status().isCreated())
-                .andDo(document(
-                        "Register Item",
+                .andDo(restDocs.document(
                         requestFields(
                             fieldWithPath("name").type(STRING)
                                 .description("상품명"),
@@ -359,8 +356,7 @@ public void deleteItem() throws Exception {
 
             // Then
             resultActions.andExpect(status().isNoContent())
-                .andDo(document(
-                    "Delete Item",
+                .andDo(restDocs.document(
                     pathParameters(
                         parameterWithName("itemId").description("상품 ID")
                     ))
@@ -380,7 +376,6 @@ public void findNewItemsWithRedis() throws Exception {
             // Given
             given(itemService.findNewItemsWithRedis(any())).willReturn(findNewItemsResponse);
 
-
             // When
             ResultActions resultActions = mockMvc.perform(
                 get("/api/v1/items/new-items")
@@ -392,7 +387,7 @@ public void findNewItemsWithRedis() throws Exception {
 
             // Then
             resultActions.andExpect(status().isOk())
-                .andDo(document("Find New Items with Redis",
+                .andDo(restDocs.document(
                     queryParameters(
                         parameterWithName("lastIdx").description("마지막에 조회한 아이템의 특성값"),
                         parameterWithName("lastItemId").description("마지막에 조회한 아이템 ID"),

diff --git a/src/test/java/com/prgrms/nabmart/domain/order/controller/OrderControllerTest.java b/src/test/java/com/prgrms/nabmart/domain/order/controller/OrderControllerTest.java
@@ -14,7 +14,6 @@
 import static org.mockito.Mockito.when;
 import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
 import static org.springframework.restdocs.headers.HeaderDocumentation.requestHeaders;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.delete;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
@@ -76,7 +75,7 @@ void findOrder() throws Exception {
             // then
             result
                 .andExpect(status().isOk())
-                .andDo(document("get-order",
+                .andDo(restDocs.document(
                     pathParameters(
                         parameterWithName("orderId").description("주문 ID")
                     ),
@@ -116,7 +115,7 @@ void findOrders() throws Exception {
             // then
             result
                 .andExpect(status().isOk())
-                .andDo(document("get-orders",
+                .andDo(restDocs.document(
                     queryParameters(
                         parameterWithName("page").description("페이지 번호")
                     ),
@@ -182,7 +181,7 @@ class UpdateOrderByCoupon {
 
         @Test
         @DisplayName("성공")
-        void createOrder() throws Exception {
+        void updateOrderByCoupon() throws Exception {
             // given
             User user = user();
             UserCoupon userCoupon = userCoupon(user);
@@ -202,6 +201,9 @@ void createOrder() throws Exception {
             result
                 .andExpect(status().isOk())
                 .andDo(restDocs.document(
+                    pathParameters(
+                        parameterWithName("orderId").description("주문 ID")
+                    ),
                     responseFields(
                         fieldWithPath("totalPrice").type(NUMBER).description("쿠폰 적용후 총 가격"),
                         fieldWithPath("discountPrice").type(NUMBER).description("쿠폰 할인 금액")
@@ -229,6 +231,9 @@ void deleteOrder() throws Exception {
             result
                 .andExpect(status().isNoContent())
                 .andDo(restDocs.document(
+                    pathParameters(
+                        parameterWithName("orderId").description("주문 ID")
+                    )
                 ));
         }
     }