1. 기존 API 문서화의 문제점과 Rest Docs

어떻게 하면 문서를 항상 최신화할 수 있을까?

API는 클라이언트에게 기능만 제공하기 때문에, API를 어떻게 사용해야하는지 문서화를해 제공한다. 개발자들은 Swagger, Postman, 심지어 워드 등 다양한 툴을 사용해 문서화를 해왔다. 기존 문서화의 가장 큰 문제점은 코드와 문서의 불일치였다. 코드와 문서가 분리되어 있다보니, 문서를 항상 최신으로 업데이트하는 것은 귀찮은 일이었고, 이때문에 누락되기 일쑤였다. Rest Docs는 코드와 문서의 강결합을 통해 이를 해결하고자 한다

2. MockMvc를 통해 snippet 생성하기

Rest Docs의 문서는 코드를 실행해 생성된 snippet의 조합으로 이루어진다

2-1. 의존성 추가

• 스프링은 MockMvc를 통해 api 테스트 후 문서화를 자동화할 수 있도록 도와주는 spring-restdocs-mockmvc 의존성을 제공한다

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

2-2. document() 메소드

• 기본적으로 requestFields snippet과 responseFields snippets을 만들 수 있다. MockMvc 테스트를 위해 입력된 요청이나 반환된 응답에 대해 모든 필드를 정의해줘야한다. 만약 프로덕션 코드와 테스트 코드는 수정되어 요청/응답이 변했지만, rest docs의 정의가 변하지 않았으면 테스트는 실패한다. API와 문서가 항상 동일하게 유지할 수 있는 것이다

    @Test
    @DisplayName("게시글을 저장할 수 있다")
    void savePost() throws Exception {
        // Given
        PostRequest postRequest = new PostRequest("test title", "");

        // When Then
        mockMvc
            .perform(post("/api/v1/posts")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(postRequest)))
            .andExpect(status().isCreated())
            .andDo(print())
            .andDo(document("save-post",  // Rest Docs
                requestFields(
                    fieldWithPath("title").type(JsonFieldType.STRING).description("post title"),
                    fieldWithPath("content").type(JsonFieldType.STRING).description("post content")
                ),
                responseFields(
                    fieldWithPath("data.id").type(JsonFieldType.NUMBER).description("id"),
                    fieldWithPath("data.title").type(JsonFieldType.STRING).description("title"),
                    fieldWithPath("data.content").type(JsonFieldType.STRING).description("content"),
                    fieldWithPath("serverDateTime").type(JsonFieldType.STRING).description("server time")
                )
            ));
    }

• 이제 테스트를 실행하면 target 디렉토리 하위의 generated-snippets에 snippet들이 생성된다

2-3. JSON 포멧팅

• 위 코드로 snippet을 생성하면 바디가 아래와 같이 한줄로 나온다. 지금은 바디가 짧아서 괜찮지만, 조금이라도 길어지면 읽기 힘들어진다.

• document() 메소드의 인자로 preprocessXXXX(prettyPrint()) 메소드를 전달해 해결할 수 있다

.andDo(document("save-post",
    preprocessRequest(prettyPrint()),  // 요청 포멧팅
    preprocessResponse(prettyPrint()),  // 응답 포멧팅
    requestFields(
        fieldWithPath("title").type(JsonFieldType.STRING).description("post title"),
        fieldWithPath("content").type(JsonFieldType.STRING).description("post content")
    ),
    responseFields(
        fieldWithPath("data.id").type(JsonFieldType.NUMBER).description("id"),
        fieldWithPath("data.title").type(JsonFieldType.STRING).description("title"),
        fieldWithPath("data.content").type(JsonFieldType.STRING).description("content"),
        fieldWithPath("serverDateTime").type(JsonFieldType.STRING).description("server time")
    )
));

3. snippet으로 API 문서 만들기

3-1. asciidoc

• asciidoc은 문서 작성을 위한 포멧이다. 위에 snippet들을 생성해보면, .adoc이라는 확장자로 생성된것을 확인할 수 있다. Spring Rest Docs는 기본적으로 asciidoc을 사용해 문서화한다

3-2. 문서 작성하기

• snippet들을 사용해 문서를 작성할 수 있다

// poject.src.docs.asciidocs 디렉토리에 작성한다 

// index.asciidoc
:hardbreaks:
ifndef::snippets[]
:snippets: ../../../target/generated-snippets    // snippet의 위치를 지정한다 
endif::[]

== 게시판

== 게시글 생성

=== POST /posts

.Request
include::{snippets}/save-post/http-request.adoc[]     // snippet을 사용
include::{snippets}/save-post/request-fields.adoc[]   // snippet을 사용

.Response
include::{snippets}/save-post/http-response.adoc[]    // snippet을 사용
include::{snippets}/save-post/response-fields.adoc[]  // snippet을 사용

3-3. asciidoctor 플러그인 추가하기

Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.

• asciidoctor를 통해 asciidoc 포멧의 문서를 HTML 같은 다양한 형식으로 변환해줄 수 있다

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

3-4. HTML 문서 생성하기

• 이제 작성한 asciidoc문서를 asciidoctor를 통해 html로 만들 수 있다. asciidoctor plugin에서 process-asciidoc을 실행한다

• targer/generated-docs 경로에 html 파일이 생성된다

참고하면 좋은 링크

Spring Rest Docs : https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

AsciiDoc : https://asciidoc-py.github.io/userguide.html