[SpringRestDocs] document 작성 상세

spring rest doc 작성 코드의 상세 내역을 분석해 보자

 

import static org.mockito.ArgumentMatchers.any;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.request;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

    @Test
    void test() throws Exception {
        BDDMockito.given(testService.test(any()))
                  .willReturn(Mono.just(new TestResult("123")));
        TestParam param = createParam();

        this.mockMvc.perform(RestDocumentationRequestBuilders.post("/test")
                                                             .content(objectMapper.writeValueAsString(param))
                                                             .contentType(MediaType.APPLICATION_JSON))
                    .andExpect(status().is2xxSuccessful())
                    .andDo(document("test/mytest1",
                                    requestFields(
                                        fieldWithPath("id").description("회원 id"),
                                        fieldWithPath("message").description("메세지"),
                                        fieldWithPath("test.name").optional().description("이름")
                                    ),
                                    responseFields(
                                        fieldWithPath("returnCode").description("응답코드"),
                                        fieldWithPath("returnMessage").description("API 응답 메시지")
                                    )));
    }

    private TestParam createParam() {
        return TestParam.builder()
                                .id("00000000-0000-0000-000000000000")
                                .message("message 123")
                                .build();
    }

 

BDDMockito

        BDDMockito.given(testService.test(any()))
                  .willReturn(Mono.just(new TestResult("123")));

TestController에 "/test"를 호출하면 내부적으로 testService를 호출하고 해당 응답이 testController에 영향을 미치게 되므로

Controller Layer 테스트에 필요한 값을 Mocking 해두는 작업

 

MockMvc

        this.mockMvc.perform(post("/test")
                              .content(objectMapper.writeValueAsString(param))
                              .contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().is2xxSuccessful())
            .andDo(document("test/mytest1",...
                    ));

mockMvc.perform를 통해 testController의 테스트 메서드 호출

해당 과정에서 필요한 content, type 등을 채워 넣어주어야 한다

andExpect : perform 이후에는 수행 후 어떠한 결과가 나타나길 기대하는지 작성 

후에 spring rest docs를 이용해 api 문서 작성을 위한 코드 작성

 

Document

.andDo(document("test/mytest1",
                requestFields(
                    fieldWithPath("id").description("회원 id"),
                    fieldWithPath("message").description("메세지"),
                    fieldWithPath("test.name").optional().description("이름")
                ),
                responseFields(
                    fieldWithPath("returnCode").description("응답코드"),
                    fieldWithPath("returnMessage").description("API 응답 메시지")
                )));

document( "..",..) 어떠한 디렉터리에 어떠한 이름으로 산출물을 나오게 할 것인지 설정

requestFields(...) 해당 요청에 어떠한 requestBody를 사용하는지 정의 

responseFields(...) 해당 요청의 응답으로 어떠한 응답값을 주는지 정의 

 

attributes

.andDo(document("test/mytest1",
                requestFields(
                    fieldWithPath("id").description("회원 id")
                        .attributes(key("defaultValue").value("testU")
                )

만약 추가적인 정보를 requestField에 추가하고 싶다면 attributes라는 메서드를 이용해 추가할 수 있다

key : 추가할 컬럼 정의

value : 해당 컬럼의 값 

 

추가적으로 해당 정보를 snippet에 나타나게 하고 싶은 경우 추가를 원하는 snippet format에 해당 정보를 추가해주어야 한다

===== Request Fields
|===
|필드명|타입|필수값|기본값|설명

{{#fields}}
|{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}}
|{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}}
|{{#tableCellContent}}{{^optional}}true{{/optional}}{{/tableCellContent}}
|{{#tableCellContent}}{{#defaultValue}}{{.}}{{/defaultValue}}{{/tableCellContent}}
|{{#tableCellContent}}{{description}}{{/tableCellContent}}

{{/fields}}
|===