Enterprise Distribution Micro Service Cloud Springcloud springboot MyBatis (24) Creating API documentation with spring Restdocs

Restdoc, generating API documentation from unit tests

Restdocs is a live snippets file that is passed through the unit test, and then snippets generates an HTM document based on the plugin.

To build a unit test class:

@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"));}    }

　　

where the @ Autoconfigurerestdocs annotation opens the Generate snippets file and specifies where to store it.

Start unit test, test pass, you will find that under the target file generated a snippets folder, its directory structure is as follows:

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

　　

By default, snippets is a asciidoctor format file, including request and reponse, in addition to two other httpie and Curl Two popular command line HTTP request modes.

So far, only the snippets file has been generated and the document needs to be generated with the snippets file.

How to use snippets

Create a new file Src/main/asciidoc/index.adoc:

= 用 Spring REST Docs 构建文档

A example output for a service running at http://localhost:8080:.requestinclude::{snippets}/home/ Http-request.adoc[].responseinclude::{snippets}/home/http-response.adoc[]

　　

这个例子非常简单，通过单元测试和一些简单的配置就能够得到api文档了。

ADOc's writing format, reference: http://docs.spring.io/spring-restdocs/docs/current/reference/html5/, here is not much to explain.

You need to use the Asciidoctor-maven-plugin plugin in its pom file plus:

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

　　

Only the MVNW Package command is required to generate the document.
Under/target/generated-docs There is a index.html, open this HTML, shown below, the interface is concise:

SOURCE SourceConclusion

Through unit testing, living ADOc files, and then using ADOc file to survive HTML, just a few simple steps to generate an API document HTML file, this HTML file you can publish through the site. The whole process is simple and has no effect on the code.

Enterprise Distribution Micro Service Cloud Springcloud springboot MyBatis (24) Creating API documentation with spring Restdocs