[springboot] 使用spring Restdocs创建API文档

这篇文章将带你了解如何用spring官方推荐的restdoc去生成api文档。本文创建一个简单的springboot工程，将http接口通过API文档暴露出来。只需要通过JUnit单元测试和Spring的MockMVC就可以生成文档。

创建工程 导入依赖

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

创建Controller 测试接口

@RestController
@RequestMapping("/test")
public class TestController {

	@RequestMapping("/sayHello")
	public String test(){
		return "Hello World";
	}
}

启动工程，访问http://localhost:8080/test/sayHello，浏览器显示：

Hello World

通过单元测试生成REST API文档

 restdocs是通过单元测试生存snippets文件，然后snippets根据插件生成htm文档的。建一个单元测试类：

package com.bo.springboot;

import com.bo.springboot.controller.TestController;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;

import javax.annotation.Resource;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@RunWith(SpringRunner.class)
@WebMvcTest(TestController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class RestDocTest {

	@Resource
	private MockMvc mockMvc;

	@Test
	public void test01() throws Exception {
		this.mockMvc.perform(get("/test/sayHello")).andDo(print()).andExpect(status().isOk())
				.andExpect(content().string(containsString("Hello World")))
				.andDo(document("test"));
	}
}

其中，@ AutoConfigureRestDocs注解开启了生成snippets文件，并指定了存放位置。启动单元测试，测试通过，你会发现在target文件下生成了一个snippets文件夹，其目录结构如下：

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

默认情况下，snippets是Asciidoctor格式的文件，包括request和reponse，另外其他两种httpie和curl两种流行的命令行的http请求模式。到目前为止，只生成了Snippets文件，接下来需要用Snippets文件生成文档。

使用用Snippets生成REST文档

创建一个新文件src/main/asciidoc/test.adoc 这个*.adoc路径应该是固定的，文件名称可自定义，*.adoc的书写格式，参考：http://docs.spring.io/spring-restdocs/docs/current/reference/html5/，这里不多讲解。

== 用 Spring REST Docs 构建API文档

This is an example output for a service running at http://localhost:8080

.request
include::{snippets}/test/http-request.adoc[]

.response
include::{snippets}/test/http-response.adoc[]

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

需要在pom文件加上asciidoctor-maven-plugin插件：

<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>test.adoc</sourceDocumentName>
                <backend>html</backend>
                <attributes>
                    <snippets>${project.build.directory}/snippets</snippets>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

注意：配置项的sourceDocumentName需要与上一步中新建的*.adoc文档名称一致。这时执行mvn package命令打包后就可以在/target/generated-docs下得到一个test.html文档了，打开文档界面如下：

参考资料 

Creating API Documentation with Restdocs

https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

SpringBoot非官方教程 | 第十篇： 用spring Restdocs创建API文档