spring restdoc 을 만들어 보자

restdoc을 쓸수도 있을 거 같아서 정리 한다. spring-boot 기준으로 작성 하였다. 기본적인 spring-boot를 안다고 가정하고 작성한다.


...

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>1.0.1.RELEASE</version>
</dependency>

....

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <includes>
            <include>**/*Documentation.java</include>
        </includes>
    </configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.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>
            <attributes>
                <snippets>${project.build.directory}/generated-snippets</snippets>
            </attributes>
        </configuration>
    </execution>
</executions>
</plugin>
<plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <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>

...

restdocs-mockmvc 디펜더시랑 plugin 을 추가하자. 필자의 파일 경로로 하지 않아도 된다. 필자는 generated-snippets 에 snippets 설정 했다. 여기에 실제 adoc 파일들이 추가된다. 그리고 테스트 케이스를 만들어야 된다. 테스트 케이스는 기존에 필자가 포스팅 한거랑 비슷한대 약간 추가 되는 부분이 있다. 살펴보자

@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = SpringTestApplication.class)
@WebAppConfiguration
@FixMethodOrder(MethodSorters.JVM)
public class AccountControllerTest {

    @Autowired
    private WebApplicationContext webApplicationContext;

    MockMvc mockMvc;


    @Autowired
    private ObjectMapper objectMapper;


    @Rule
    public RestDocumentation restDocumentation =
            new RestDocumentation("target/generated-snippets");

    @Before
    public void before() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.webApplicationContext)
                .apply(documentationConfiguration(this.restDocumentation))
//                .alwaysDo(document("{method-name}/{step}/"))
                .alwaysDo(document("{class-name}/{method-name}/"))
                .build();
    }

    @Test
    public void getAccounts() throws Exception {
        this.mockMvc.perform(get("/accounts").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.[0].name", is("wonwoo")));
    }

    @Test
    public void getAccount() throws Exception {
        this.mockMvc.perform(get("/account/{id}", 1).accept(MediaType.APPLICATION_JSON))
                .andDo(print())
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.name", is("wonwoo")));
    }

    @Test
    public void createAccount() throws Exception {
        Account account = new Account();
        account.setName("wonwoo123");
        this.mockMvc.perform(post("/account").contentType(MediaType.APPLICATION_JSON).accept(MediaType.APPLICATION_JSON)
                    .content(objectMapper.writeValueAsString(account)))
                .andDo(print())
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.name",is("wonwoo123")));
    }
}

나머진 일반 테스트 케이스처럼 작성하면 되고 before 부분만 변경 되었다. before의 alwaysDo 메소드에 있는 class-name과 method-name은 위에서 말했던 generated-snippets/* 폴더 아래에 classname/methodname/ 형식으로 추가된다. 작성 후에 테스트를 실행 하여 보자. 만약 성공 되었다면 target/generated-snippets/ 아래 폴더에 파일들이 생성 되어있는걸 볼 수 있다. 그리고 나서 src/main/asciidoc/index.adoc 를 추가하자. (필자 기준)

= RESTful Notes API Guide
Andy Wilkinson;
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:sectlinks:

[[overview]]
= Overview

[[overview-http-verbs]]
== HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP verbs.

|===
| Verb | Usage

| `GET`
| Used to retrieve a resource

| `POST`
| Used to create a new resource

| `PATCH`
| Used to update an existing resource, including partial updates

| `DELETE`
| Used to delete an existing resource
|===

[[overview-http-status-codes]]
== HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP status codes.

|===
| Status code | Usage

| `200 OK`
| The request completed successfully

| `201 Created`
| A new resource has been created successfully. The resources URI is available from the responses
`Location` header

| `204 No Content`
| An update to an existing resource has been applied successfully

| `400 Bad Request`
| The request was malformed. The response body will include an error providing further information

| `404 Not Found`
| The requested resource did not exist
|===


== 사용자 리스트 조회 [get]

사용자를조회


include::{snippets}/account-controller-test/get-accounts/curl-request.adoc[]

=== 요청 구조

==== 요청 파라미터들

include::{snippets}/account-controller-test/get-accounts/http-request.adoc[]

=== 응답 구조

==== 응답 파라미터들

include::{snippets}/account-controller-test/get-accounts/http-response.adoc[]



== 사용자 조회 [get]

사용자를조회


include::{snippets}/account-controller-test/get-account/curl-request.adoc[]

=== 요청 구조

==== 요청 파라미터들

include::{snippets}/account-controller-test/get-account/http-request.adoc[]

=== 응답 구조

==== 응답 파라미터들

include::{snippets}/account-controller-test/get-account/http-response.adoc[]


== 사용자 입력 [post]

사용자를조회


include::{snippets}/account-controller-test/create-account/curl-request.adoc[]

=== 요청 구조

==== 요청 파라미터들

include::{snippets}/account-controller-test/create-account/http-request.adoc[]

=== 응답 구조

==== 응답 파라미터들

include::{snippets}/account-controller-test/create-account/http-response.adoc[]

윗 부분은 spring에서 퍼온거라.. asciidoc이라는 문법이다. asciidoc-syntax-quick-reference 문법은 여기서 참고. == 사용자 리스트 조회 [get] 이 부분 부터가 필자가 만들었다. 이쁘진 않지만.. 나머지는 그냥 다 문법이고 추가 해야 되는 부분이 있는데 include하는 이 부분이다. 위에서 말했던 파일들을 include 하는 부분이다. 저기에 각각의 페이지가 include 된다. 실제 파일들이 어떻게 생겼는지 보자. curl이 작성 되어있다. 파일명은 curl-request.adoc로 떨궈진다.

[source,bash]
----
$ curl http://localhost:8080/accounts -i -H Accept: application/json
----

다음으로 reqeust 정보이다. 실제 rest api 의 method, resource, message 정보들이 적혀있다. (물론 지금은 메시지가 없어서)

[source,http]
----
GET /accounts HTTP/1.1
Accept: application/json
Host: localhost

----

마지막으로 response 정보이다. 실제 서버에서 내려 받은 정보를 보여준다.

[source,http]
----
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 81

[ {
  "id" : 1,
  "name" : "wonwoo"
}, {
  "id" : 2,
  "name" : "kevin"
} ]
----

메이븐 기준으로 되어있으니 메이븐을 실행해보자.

mvn install

그러면 target/generated-docs 아래 index.html 파일이 생성 되어 있을 것이다. 한번 열어 보자! 그럼 깔끔한 api 문서가 만들어져있다. spring-doc

잘 실행되었다면 위와 같은 화면을 볼 수 있을 것이다.