Spring REST Docs 사용법

RESTful API를 문서화는 언제나 이슈가 되고 있는 듯 하다.

여러가지 문서화 방법이 있는데

여기서는 Spring REST Docs 라이브러리를 이용해서 문서화 하는 방법에 대해 알아보자.

pom.xml

<dependency>

<groupId>org.springframework.restdocs</groupId>

<artifactId>spring-restdocs-mockmvc</artifactId>

<version>1.1.2.RELEASE</version>

</dependency>

...

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-surefire-plugin</artifactId>

<version>2.19.1</version>

<configuration>

<includes>

<include>**/*Documentation.java</include>

</includes>

</configuration>

</plugin>

<plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<version>1.5.2</version>

<executions>

<execution>

<id>generate-docs</id>

<phase>prepare-package</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<configuration>

<backend>html</backend>

<doctype>book</doctype>

<attributes>

<snippets>${snippetsDirectory}</snippets>

</attributes>

</configuration>

</execution>

</executions>

</plugin>

<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>

JUnit 코드 작성 및 실행

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;

import org.junit.Before;

import org.junit.Rule;

import org.junit.runner.RunWith;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.restdocs.JUnitRestDocumentation;

import org.springframework.test.context.ContextConfiguration;

import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

import org.springframework.test.context.web.WebAppConfiguration;

import org.springframework.test.web.servlet.MockMvc;

import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import org.springframework.web.context.WebApplicationContext;

import com.my.app.configuration.RootContextConfig;

import com.my.app.configuration.ServletContextConfig;

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.request.MockMvcRequestBuilders.get;

import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;

import org.junit.Test;

import org.springframework.http.MediaType;

@RunWith(SpringJUnit4ClassRunner.class)

@ContextConfiguration(classes = { RootContextConfig.class, ServletContextConfig.class })

@WebAppConfiguration

public class UserControllerTest {

protected MockMvc mockMvc;

@Autowired

private WebApplicationContext context;

@Rule

public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");

@Before

public void setUp() {

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)

.apply(documentationConfiguration(this.restDocumentation)).build();

}

@Test

public void testGetUsers() throws Exception {

mockMvc.perform(get("/users").accept(MediaType.APPLICATION_JSON_UTF8_VALUE))

.andDo(print())

.andDo(document("/users", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint())));

}

}

JUnit이 성공하면

메이븐 properties 태그에 설정한 snippetsDirectory 경로에 아래와 같이 adoc 파일 4개가 생긴다.

(경로는 target/generated-snippets)

curl-request.adoc

httpie-request.adoc

http-request.adoc

http-response.adoc

/src/main/asciidoc 경로에 api-docs.adoc 파일 작성

= RESTful API Documents

:toc: left

= Overview

RESTful API 문서

[[user]]

== 사용자

사용자

=== request

include::{snippets}/users/http-request.adoc[]

=== response

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

프로젝트 -> Run As -> Maven build -> 창이 뜨는데 Goals 항목에 package 입력 후 Skip Tests 체크 후 Run 클릭

(메이븐 빌드할 때 JUnit 실행시켜서 문서를 만드는 것도 가능. Skip Tests 체크 해제 필요)

target/generated-docs

target/classes/static

폴더에 api-docs.html 문서 생성됨

결과

참고사이트

Spring REST Docs: http://docs.spring.io/spring-restdocs/docs/1.1.2.RELEASE/reference/html5/

Asciidoctor User Manual: http://asciidoctor.org/docs/user-manual/

Asciidoctor Quick Reference: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

끝.