企業分佈式微服務雲SpringCloud SpringBoot mybatis （三十五）Restdoc生成api文檔

Restdoc,經過單元測試生成api文檔

restdocs是經過單元測試生存snippets文件，而後snippets根據插件生成htm文檔的。

建一個單元測試類：

@RunWith(SpringRunner.class)
@WebMvcTest(HomeController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk())
                .andExpect(content().string(containsString("Hello World")))
                .andDo(document("home"));
    }
}

　　

其中，@ AutoConfigureRestDocs註解開啓了生成snippets文件，並指定了存放位置。

啓動單元測試，測試經過，你會發如今target文件下生成了一個snippets文件夾，其目錄結構以下：

└── target
    └── snippets
        └── home
            └── httpie-request.adoc
            └── curl-request.adoc
            └── http-request.adoc
            └── http-response.adoc

　　

默認狀況下，snippets是Asciidoctor格式的文件，包括request和reponse，另外其餘兩種httpie和curl兩種流行的命令行的http請求模式。

到目前爲止，只生成了Snippets文件，須要用Snippets文件生成文檔。

怎麼用Snippets

建立一個新文件src/main/asciidoc/index.adoc ：

= 用 Spring REST Docs 構建文檔

This is an example output for a service running at http://localhost:8080:

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

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

　　

這個例子很是簡單，經過單元測試和一些簡單的配置就可以獲得api文檔了。

adoc的書寫格式，參考:http://docs.spring.io/spring-restdocs/docs/current/reference/html5/，這裏很少講解。

須要使用asciidoctor-maven-plugin插件，在其pom文件加上：

<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>
                <sourceDocumentName>index.adoc</sourceDocumentName>
                <backend>html</backend>
                <attributes>
                    <snippets>${project.build.directory}/snippets</snippets>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

　　

這時只須要經過mvnw package命令就能夠生成文檔了。 
在/target/generated-docs下有個index.html，打開這個html,顯示以下，界面還算簡潔：

源碼來源

經過單元測試，生存adoc文件，再用adoc文件生存html，只須要簡單的幾步就能夠生成一個api文檔的html文件，這個html文件你能夠通網站發佈出去。整個過程很簡單，對代碼無任何影響。