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

Source: Internet
Author: User

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

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.