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

文档"/>

[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 {@Resourceprivate MockMvc mockMvc;@Testpublic 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的书写格式，参考：/，这里不多讲解。

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

/

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