今天给大家分享一个能通过代码自动生成文档技术,Spring Rest Doc过在单元测试中额外添加 API 信息描述,从而自动生成对应的文档片段。 下面通过一个简单的例子演示下如何快速上手的。在Spring Boot项目中添加maven 依赖
org.springframework.boot
spring-boot-starter-test
test
org.springframework.restdocs
spring-restdocs-mockmvc
test
在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;
@BeforeEach
public void init(WebApplicationContext applicationContext, RestDocumentationContextProvider contextProvider){
mockMvc = MockMvcBuilders.webAppContextSetup(applicationContext)
.apply(MockMvcRestDocumentation.documentationConfiguration(contextProvider))
.build();
}
@Test
void 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文档
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
generate-docs
prepare-package
process-asciidoc
index.adoc
html
${project.build.directory}/generated-snippets
运行mvn package
命令后可以在target/generated-docs看见index.html,效果如下
Spring Rest Docs只是提供生成文档片而已,要生成一份完整的问题,仍然需要手动去编写index.adoc
,引用文档片,通过组合的方式变成一个自己想要的文档。这个跟Swagger完去自动化生成的文档有很多区别的。两者在使用上也有很多不同。
我个人感觉 Spring Rest Docs心中完美的API文档实现,Mock测试通过生成的文档,保证每一个文档都是可用、准确的,减少人为交流。又可以根据自身需求,自由组合文档内容,既有严谨性、又具备一定灵活性,奈何编写一份API文档需要更长工时,在方便、快捷上完全不能与Swagger比较,在日常开发API文档,大多数都是使用Swagger为主,但是如果现在还有团队使用Yapi这类手动编写API文档,我建议使用Spring Rest Docs替代,让API更严谨。