[데브코스] Spring Rest Docs

W8D5 - MockMvc를 활용한 테스트와 Rest Docs 문서화에 대해 알아보자

MockMvc

• Endpoint(컨트롤러) 테스트할 때 요청/응답 테스트를 쉽게 할 수 있도록 해주는 모듈
• mockito 모듈이나 restdocs 모듈을 의존성에 추가하여 사용할 수 있다.

설정

pom.xml

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <scope>test</scope>
</dependency>

사용법

• @AutoConfigureMockMvc : 테스트 클래스에 해당 어노테이션을 달아줘야함
• MockMvc : Bean으로 띄워서 사용
• ObjectMapper : 메시지컨버터 역할 해준다고 생각하믄 됨
• perform으로 요청 만들어서 보내고 -> andExpect에서 받고 검증 -> andDo로 출력

@AutoConfigureMockMvc
class TestClass {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    ObjectMapper objectMapper;

    @Test
    void testMethod() {
        // POST
        mockMvc.perform(post("/URL")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(post로 넘어오는 값)))
                .andExpect(status().isOk())
                .andDo(print());

        // GET
        mockMvc.perform(get("/URL/{pathVal}", pathVal)
                        .param("파라미터명", 파라미터 값)
                        .contentType(MediaType.APPLICATION_JSON)
                .andExpect(status().isOk())
                .andDo(print());
    }
}

Rest Docs

• MockMvc를 사용해 Controller를 테스트할때 Rest API 명세까지 문서화할 수 있게해주는 기능
• 요청/응답 데이터(json) 형식을 모두 테스트하고 하나라도 일치하지 않는다면 오류발생

설정

• <plugins> 부분에 다음 플러그인을 추가해줘야 한다.
• 테스트 후 Rest API 명세서가 .html 형태로 빌드되도록 추가 설정한것

pom.xml

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>${spring-restdocs.version}</version>
        </dependency>
    </dependencies>
</plugin>

AsciiDoc

• 이건 IntelliJ에서 .adoc 확장자 파일을 읽도록 도와주는 플러그인이다. (반드시 설치)
• Windows 기준 Ctrl + Alt + S -> Plugins -> Marketplace에서 AsciiDoc 검색 후 설치

• 디렉토리 규칙
  • AsciiDoc 설치 전 : /src/main 하위에 /asciidoc/index.adoc 이 존재해야 함
  • AsciiDoc 설치 후 : /src 하위에 /docs/asciidoc/index.adoc이 존재해야 함

Rest Docs 생성

• mockMvc 테스트 결과에 데이터 검증 부분을 추가해준다
  • andDo("문서이름", requestFields(), responseFields())

mockMvc.perform(post("/URL")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(post로 넘어오는 값)))
                .andExpect(status().isOk())
                .andDo(print())
                .andDo(document(    // 데이터 검증 + 문서화 추가
                        "문서이름",
                        // 요청
                        requestFields(
                                fieldWithPath("데이터명").type(JsonFieldType.타입).description("설명"),
                                fieldWithPath("데이터명.하위데이터명").type(JsonFieldType.타입).description("설명"),
                                fieldWithPath("데이터명[].하위데이터명").type(JsonFieldType.타입).description("설명")
                        ),
                        // 응답
                        responseFields(
                                fieldWithPath("데이터명").type(JsonFieldType.타입).description("설명")
                        )
                ));

• 테스트코드 실행시 자동으로 Rest Docs가 빌드된다.
• 빌드 결과물은 /target/generated-snippets/문서이름/ 경로에 .adoc 형태로 저장된다.

문서화하기

• AsciiDoc 플러그인의 도움을 받아 결과를 볼 순 있지만 가독성이 떨어진다.
• 따라서 생성했던 index.adoc에서 결과물을 커스텀할 수 있다.
• asciidoc의 문법은 이 블로그를 참고하자

index.adoc 간단한 예시

:hardbreaks:
ifndef::snippets[]
:snippets: ../../../target/generated-snippets
endif::[]

== h2

=== h3

.Request
include::{snippets}/문서이름/http-request.adoc[]
include::{snippets}/문서이름/request-fields.adoc[]

.Response
include::{snippets}/문서이름/http-response.adoc[]
include::{snippets}/문서이름/response-fields.adoc[]

html로 변환

• 위에서 작성한 index.adoc를 참조하여 html 문서로 만들 수 있다.
• maven에서 아래와 같이 process-asciidoc을 실행해 빌드하면 …

• 아래와 같이 generated-docs 폴더에 index.adoc이 html로 변환된 것을 볼 수 있다!

• 이 기능에 감명받았다. 나중에 프로젝트할 때 테스트 + 문서화를 해서 꼭!!!! 웹페이지로 만들것이다…