Shulou(Shulou.com)06/02 Report--

This article shows you how to use spring Restdocs to create API documents, the content is concise and easy to understand, can definitely brighten your eyes, through the detailed introduction of this article, I hope you can get something.

Preparatory work

You need 15min.

Jdk 1.8

Maven 3.0 +

Idea

Create a project

Introduce dependencies, their pom files:

Org.springframework.boot spring-boot-starter-web org.springframework.boot spring-boot-starter-test test org.springframework.restdocs spring-restdocs-mockmvc test

Open springboot through @ SpringBootApplication

@ SpringBootApplicationpublic class Application {public static void main (String [] args) {SpringApplication.run (Application.class, args);}}

In springboot, you usually create a controller:

@ RestControllerpublic class HomeController {@ GetMapping ("/") public Map greeting () {return Collections.singletonMap ("message", "Hello World");}}

Start the project, visit localhost:8080, and the browser displays:

{"message": "Hello World"}

Prove that the interface has been written, but how to survive the api document through restdoc

Restdoc to generate api documents through unit tests

Restdocs survives the snippets file through unit tests, and then snippets generates the htm document based on the plug-in.

Create 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")) }}

The @ AutoConfigureRestDocs annotation turns on the generation of snippets files and specifies the location to store them.

Start the unit test, pass the test, and you will find that a snippets folder is generated under the target file, with the following directory structure:

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

By default, snippets is a file in Asciidoctor format, including request and reponse, and the other two popular command-line http request modes, httpie and curl.

So far, only Snippets files have been generated, and you need to use Snippets files to generate documents.

How to use Snippets

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

The example of building a document This is an example output for a service running at http://localhost:8080:.requestinclude::{snippets}/home/http-request.adoc[].responseinclude::{snippets}/home/http-response.adoc[] with Spring REST Docs is very simple, and you can get the api document through unit tests and some simple configuration.

The writing format of adoc, refer to: http://docs.spring.io/spring-restdocs/docs/current/reference/html5/, not explained here.

You need to use the asciidoctor-maven-plugin plug-in, adding to its pom file:

Org.asciidoctor asciidoctor-maven-plugin generate-docs prepare-package process-asciidoc index.adoc html ${project.build.directory} / snippets

At this point, you only need to generate the document through the mvnw package command.

There is an index.html under / target/generated-docs. Open the html and display as follows. The interface is fairly simple:

Through the unit test, survive the adoc file, and then use the adoc file to survive the html, just a few simple steps to generate an api document html file, this html file you can publish through the website. The whole process is simple and has no effect on the code.

Source code download: https://github.com/forezp/SpringBootLearning

The above is how to create API documents with spring Restdocs. Have you learned any knowledge or skills? If you want to learn more skills or enrich your knowledge reserve, you are welcome to follow the industry information channel.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.