Enterprise Distribution Micro Service Cloud Springcloud springboot MyBatis (22) Restdoc Generate API documentation

Preparatory work

• You need 15min.
• JDK 1.8
• Maven 3.0+
• Idea

Create a project

To introduce dependencies, its pom file:

<dependencies>        <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>        </dependency>        <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>    </dependencies>

　　

Through @springbootapplication, open springboot

@SpringBootApplicationpublic class Application {public    static void Main (string[] args) {        Springapplication.run (Application.class, args);}    }

　　

In Springboot, you typically create a controller:

@RestControllerpublic class HomeController {    @GetMapping ("/") public    map<string, object> greeting () {        return Collections.singletonmap ("message", "Hello World");}    }

　　

Launch project, Access localhost:8080, browser display:

{“message”:”Hello World”}

Prove that the interface has been written, but how to survive API documentation through Restdoc?

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:

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 Source

Enterprise Distribution Micro Service Cloud Springcloud springboot MyBatis (22) Restdoc Generate API documentation