Hello, everyone. Meet again. I'm Jun Quan.

preparation

You need 15 min
Jdk 1.8
maven 3.0+
idea

Create project

Import dependency, and 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>

Start springboot through @ SpringBootApplication

@SpringBootApplication
public class Application {

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

A controller is usually created in springboot:

@RestController
public class HomeController {

    @GetMapping("/")
    public Map<String, Object> 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 api documents through restdoc

Restdoc, generating api documents through unit tests

restdocs survives snippets files through unit tests, and then snippets generates htm documents according to plug-ins.

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 enables the generation of snippets files and specifies the storage location.

Start the unit test and pass the test. You will find that a snippets folder is generated under the target file. Its directory structure is as follows:

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

By default, snippets are files in ASCII locator format, including request and reply, and the other two popular command-line http request modes, httpie and curl.

So far, only Snippets files have been generated, and documents need to be generated with Snippets files.

How to use Snippets

Create a new file Src / main / ASCII Doc / index adoc :

Building documents with 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[]

This example is very simple. You can get the api document through unit test and some simple configuration.

For the writing format of adoc, refer to: http://docs.spring.io/spring-... , I won't explain much here.

You need to use the asciidoctor Maven plugin plug-in and add the following to its pom file:

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

At this time, you only need to use the mvnw package command to generate documents. There is an index under / target / generated docs html, open this html, the display is as follows, and the interface is relatively simple:

epilogue

Through the unit test, you can save the ADO file, and then use the ADO file to save the html. In a few simple steps, you can generate an html file of api document, which you can publish through the website. The whole process is simple and has no impact on the code.

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

Publisher: full stack programmer, stack length, please indicate the source for Reprint: https://javaforall.cn/108171.html Original link: https://javaforall.cn