[SpringRestDocs] Spring REST Docs이란 & 사용해보기

Spring REST Docs

Spring REST Docs는 스프링 프레임워크에서 제공하는 API 문서 자동화 도구

테스트를 실행하면서 생성한 요청과 응답을 기반으로 문서를 생성한다

-> 테스트 코드를 작성하면, API 문서는 덤으로! 

 

테스트가 성공하면, 그 테스트에 대한 asciidoc 스니펫이 생성

-> 생성된 스니펫들 중에, 내가 문서에 명시하고 싶은 녀석들을 골라서 api문서 작성 

 

Asciidoc

adoc(Asciidoc)은 Markdown과 마찬가지로 문서 작성을 위한 경량형 마크업 언어 

문서 자체는 .adoc 확장자의 text문서에 불과하고, Asciidoctor(https://asciidoctor.org/) 를 이용해 html이나 pdf 등으로 활용할 수 있다

 

사용해 보기

Maven dependency

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

Maven Plugin

      <plugin> <!-- adoc 생성을 위한 plugin -->
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>2.2.1</version>
        <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>2.0.7.RELEASE</version>
          </dependency>
        </dependencies>
      </plugin>
      <plugin> <!-- 생성된 문서를 output jar에 넣기 위한 plugin -->
        <artifactId>maven-resources-plugin</artifactId>
        <version>2.7</version>
        <executions>
          <execution>
            <id>copy-resources</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>
                ${project.build.outputDirectory}/static/docs
              </outputDirectory>
              <resources>
                <resource>
                  <directory>
                    ${project.build.directory}/generated-docs
                  </directory>
                </resource>
              </resources>
            </configuration>
          </execution>
        </executions>
      </plugin>

테스트 코드 작성

테스트 클래스 설정

@WebMvcTest(controllers = MyController.class)
@ExtendWith({RestDocumentationExtension.class})
@AutoConfigureRestDocs
class MyControllerTest {
    @Autowired
    private MockMvc mockMvc;

    // ...
}

테스트 메서드 작성 

    @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();
    }

테스트 메서드 실행 시 아래 위치에 snippets 파일 자동 생성

 

이제 생성된 snippets 파일을 기반으로 원하고 싶은 API 가이드 문서 작성 

= API 문서
:toc: left

== myTest1

include::{snippets}/test/myTest1/request-fields.adoc[]

=== example

==== Http Body

include::{snippets}/test/myTest1/request-body.adoc[]
include::{snippets}/test/myTest1/curl-request.adoc[]

==== Http Response

include::{snippets}/test/myTest1/response-fields.adoc[]

발송 성공

include::{snippets}/test/myTest1/http-response.adoc[]

접속

http://localhost:8080/docs/{문서이름}.html

ex) http://localhost:8080/docs/api-doc.html

 

 

작성 상세 : https://kkang-joo.tistory.com/51