今天给大家分享一个能通过代码自动生成文档技术，Spring Rest Doc过在单元测试中额外添加 API 信息描述，从而自动生成对应的文档片段。 下面通过一个简单的例子演示下如何快速上手的。在Spring Boot项目中添加maven 依赖
<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>
在controller添加接口
@PostMapping("/show/entity")public Dog getDog(@RequestBody Dog dog){return dog;}
编写测试用例，并且输出文档。
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.result.MockMvcResultMatchers;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;@WebMvcTest
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
class DogControllerTest {private MockMvc mockMvc;@BeforeEachpublic void init(WebApplicationContext applicationContext, RestDocumentationContextProvider contextProvider){mockMvc = MockMvcBuilders.webAppContextSetup(applicationContext).apply(MockMvcRestDocumentation.documentationConfiguration(contextProvider)).build();}@Testvoid getDog() throws Exception {String json = "{\"id\": 12,\"name\":\"Miki\"}";mockMvc.perform(RestDocumentationRequestBuilders.post("/dog/show/entity").content(json).contentType(MediaType.APPLICATION_JSON_VALUE)).andExpect(MockMvcResultMatchers.status().isOk()) //成功响应.andExpect(MockMvcResultMatchers.jsonPath("name","Miki").exists()) //结果匹配.andDo(MockMvcRestDocumentation.document("dog",requestFields(PayloadDocumentation.fieldWithPath("name").description("名字"),PayloadDocumentation.fieldWithPath("id").description("实体id")),PayloadDocumentation.responseFields(PayloadDocumentation.fieldWithPath("name").description("名字"),PayloadDocumentation.fieldWithPath("id").description("实体id")))); //输出文档}
}
在target目录可以看到生成文档
在target/generated-snippets/dog目录下会生成文档片段 例如curl-request.adoc 就是curl执行http命令执行参数，直接copy就可以执行了
$ curl 'http://localhost:8080/dog/show/entity' -i -X POST \-H 'Content-Type: application/json' \-d '{"id": 12,"name":"Miki"}'
要想生成一个完整文档，这些文档全部合并成一个文档，还需要编写一个集合文档。在项目src/main/asciidoc/目录下新增文件index.adoc
= 这是标题一
:toc: left文章段落== 这是标题二.curl-request
include::{snippets}/dog/curl-request.adoc[].http-request
include::{snippets}/dog/http-request.adoc[].request-fields
include::{snippets}/dog/request-fields.adoc[].response-body
include::{snippets}/dog/response-body.adoc[].response-fields
include::{snippets}/dog/response-fields.adoc[]
使用asciidoctor-maven-plugin 插件生成html文档
<plugin><groupId>org.asciidoctor</groupId><artifactId>asciidoctor-maven-plugin</artifactId><version>1.5.3</version><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}/generated-snippets</snippets></attributes></configuration></execution></executions></plugin>
运行mvn package命令后可以在target/generated-docs看见index.html,效果如下
Spring Rest Docs只是提供生成文档片而已，要生成一份完整的问题，仍然需要手动去编写index.adoc,引用文档片，通过组合的方式变成一个自己想要的文档。这个跟Swagger完去自动化生成的文档有很多区别的。两者在使用上也有很多不同。
生成方式:
- Swagger: 只有在方法、实体对象添加注解声明即可，简单、方便，对代码有一定侵入性。文档生成依赖项目提供服务，属于在线文档，支持离线导入文档。
- Spring Rest Docs： 手动编写每一个http 方法的测试用例，并且还有标注每一个请求参数的含义，这些都是通过代码来实现的。对开发人员有一定要求，工作量也有不少。必须测试通过了才会生成相应文档，这个保证了文档有效性。
使用场景;
- Swagger： 因为文档提供必须项目提供http服务在一起，对网络环境有一定要求，对接口权限不敏感。比如提供给同一个开发部门的前端开发使用。Swagger更多适合在同一个开发小组内，要求文档提供速度较快，实时性高，基本就是写完一个http接口，就能提供相应的文档。
- Spring Rest Docs：作为一个离线文档，比较适合跨部门或者跨厂商之间文档提供，像这种一般没有本地开发环境，调试不方便，很需要文档提供curl调用样例。接口的变动不会太频繁的，有着完整测试用例覆盖。
我个人感觉 Spring Rest Docs心中完美的API文档实现，Mock测试通过生成的文档，保证每一个文档都是可用、准确的，减少人为交流。又可以根据自身需求，自由组合文档内容，既有严谨性、又具备一定灵活性，奈何编写一份API文档需要更长工时，在方便、快捷上完全不能与Swagger比较，在日常开发API文档，大多数都是使用Swagger为主，但是如果现在还有团队使用Yapi这类手动编写API文档，我建议使用Spring Rest Docs替代，让API更严谨。
