Spring Rest Docs使用

話說程序員最討厭兩樣東西，接手項目時沒有任何文檔，自己開發項目必須提供文檔。

今天給大家分享一個能通過代碼自動生成文檔技術，Spring Rest Doc過在單元測試中額外添加 API 信息描述，從而自動生成對應的文檔片段。
下面通過一個簡單的例子演示下如何快速上手的。在Spring Boot項目中添加maven 依賴

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

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

在controller添加接口

    @PostMapping("/show/entity")
    public Dog getDog(@RequestBody Dog dog){
        return dog;
    }

編寫測試用例，並且輸出文檔。

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.result.MockMvcResultMatchers;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;


@WebMvcTest
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
class DogControllerTest {

    private MockMvc mockMvc;

    @BeforeEach
    public void init(WebApplicationContext applicationContext, RestDocumentationContextProvider contextProvider){
        mockMvc = MockMvcBuilders.webAppContextSetup(applicationContext)
                .apply(MockMvcRestDocumentation.documentationConfiguration(contextProvider))
                .build();
    }

    @Test
    void getDog() throws Exception {
        String json = "{\"id\": 12,\"name\":\"Miki\"}";
        mockMvc.perform(RestDocumentationRequestBuilders.post("/dog/show/entity")
                        .content(json)
                        .contentType(MediaType.APPLICATION_JSON_VALUE))
                .andExpect(MockMvcResultMatchers.status().isOk()) //成功響應
                .andExpect(MockMvcResultMatchers.jsonPath("name","Miki").exists()) //結果匹配
                .andDo(MockMvcRestDocumentation.document("dog",
                        requestFields(PayloadDocumentation.fieldWithPath("name").description("名字"),
                                PayloadDocumentation.fieldWithPath("id").description("實體id")),
                        PayloadDocumentation.responseFields(
                                PayloadDocumentation.fieldWithPath("name").description("名字"),
                                PayloadDocumentation.fieldWithPath("id").description("實體id")
                        ))); //輸出文檔
    }
}

在target目錄可以看到生成文檔

在target/generated-snippets/dog目錄下會生成文檔片段
例如curl-request.adoc 就是curl執行http命令執行參數，直接copy就可以執行了

$ curl 'http://localhost:8080/dog/show/entity' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"id": 12,"name":"Miki"}'

要想生成一個完整文檔，這些文檔全部合併成一個文檔，還需要編寫一個集合文檔。在項目src/main/asciidoc/目錄下新增文件index.adoc

= 這是標題一
:toc: left

文章段落

== 這是標題二

.curl-request
include::{snippets}/dog/curl-request.adoc[]

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

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

.response-body
include::{snippets}/dog/response-body.adoc[]

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

使用asciidoctor-maven-plugin 插件生成html文檔

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <id>generate-docs</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <sourceDocumentName>index.adoc</sourceDocumentName>
                            <backend>html</backend>
                            <attributes>
                                <snippets>${project.build.directory}/generated-snippets</snippets>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

運行mvn package命令後可以在target/generated-docs看見index.html,效果如下

Spring Rest Docs只是提供生成文檔片而已，要生成一份完整的問題，仍然需要手動去編寫index.adoc,引用文檔片，通過組合的方式變成一個自己想要的文檔。這個跟Swagger完去自動化生成的文檔有很多區別的。兩者在使用上也有很多不同。

生成方式:

• Swagger: 只有在方法、實體對象添加註解聲明即可，簡單、方便，對代碼有一定侵入性。文檔生成依賴項目提供服務，屬於在線文檔，支持離線導入文檔。
• Spring Rest Docs： 手動編寫每一個http 方法的測試用例，並且還有標註每一個請求參數的含義，這些都是通過代碼來實現的。對開發人員有一定要求，工作量也有不少。必須測試通過了纔會生成相應文檔，這個保證了文檔有效性。

使用場景;

• Swagger： 因爲文檔提供必須項目提供http服務在一起，對網絡環境有一定要求，對接口權限不敏感。比如提供給同一個開發部門的前端開發使用。Swagger更多適合在同一個開發小組內，要求文檔提供速度較快，實時性高，基本就是寫完一個http接口，就能提供相應的文檔。
• Spring Rest Docs：作爲一個離線文檔，比較適合跨部門或者跨廠商之間文檔提供，像這種一般沒有本地開發環境，調試不方便，很需要文檔提供curl調用樣例。接口的變動不會太頻繁的，有着完整測試用例覆蓋。
  我個人感覺 Spring Rest Docs心中完美的API文檔實現，Mock測試通過生成的文檔，保證每一個文檔都是可用、準確的，減少人爲交流。又可以根據自身需求，自由組合文檔內容，既有嚴謹性、又具備一定靈活性，奈何編寫一份API文檔需要更長工時，在方便、快捷上完全不能與Swagger比較，在日常開發API文檔，大多數都是使用Swagger爲主，但是如果現在還有團隊使用Yapi這類手動編寫API文檔，我建議使用Spring Rest Docs替代，讓API更嚴謹。