本人所在的项目团队分为前端开发和后端开发两个子小组,前后端通过RESTfull API通信,过去一般都要用word来写API文档,随着需求的变化和开发的深入,往往还要多次更新API文档,这会给开发人员增加不少工作量。最近,项目组引入了Springfox和Spring Rest Docs来自动生成文档,本文做个记录。
1.预备知识
2.关于Springfox和Spring Rest Docs
借用官网的一句话介绍Springfox:Automated JSON API documentation for API's built with Spring。我理解就是为基于Spring构建的API自动生成文档。
最终目标是为我们的项目生成如下形式的文档:
Springfox形式的文档
Spring Rest Docs:Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test. 本文主要用Spring Rest Docs来生成API的例子。
3.在线文档与离线文档
必须要说明,这里的目标是自动生成被官方称为staticdocs的文档(暂且理解为离线文档),对应Springfox官方文档的6. Configuring springfox-staticdocs。如果是在线文档,可以参考这篇博文:Spring Boot中使用Swagger2构建强大的RESTful API文档
4.从Maven依赖开始
在Spring Boot中使用Swagger2构建强大的RESTful API文档这篇博文中已经知道了如何生成在线文档,其实我们的思路就是把在线文档转成staticdocs形式的文档,因此该篇博文引用的依赖都要引入,Spring Rest Docs的依赖spring-restdocs-mockmvc,离线文档的依赖springfox-staticdocs,因为要在单元测试的时候生成文档,所以再加测试相关的spring-boot-starter-test。
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-test
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
org.springframework.restdocs
spring-restdocs-mockmvc
1.1.2.RELEASE
test
io.springfox
springfox-staticdocs
2.6.1
com.alibaba
fastjson
1.2.8
5.Maven插件
asciidoctor-maven-plugin插件是用来把Asciidoc格式转成HTML5格式。
org.springframework.boot
spring-boot-maven-plugin
org.apache.maven.plugins
maven-surefire-plugin
**/*Documentation.java
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
${project.basedir}/docs/asciidoc
index.adoc
book
left
3
${project.build.directory}/asciidoc
output-html
test
process-asciidoc
html5
6.文档生成类的编写
先贴代码:
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class Documentation {
private String snippetDir = "target/generated-snippets";
private String outputDir = "target/asciidoc";
//private String indexDoc = "docs/asciidoc/index.adoc";
@Autowired
private MockMvc mockMvc;
@After
public void Test() throws Exception{
// 得到swagger.json,写入outputDir目录中
mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
.andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
.andExpect(status().isOk())
.andReturn();
// 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
// 这个outputDir必须和插件里面标签配置一致
Swagger2MarkupConverter.from(outputDir + "/swagger.json")
.withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
.withExamples(snippetDir)
.build()
.intoFolder(outputDir);// 输出
}
@Test
public void TestApi() throws Exception{
mockMvc.perform(get("/student").param("name", "xxx")
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("getStudent", preprocessResponse(prettyPrint())));
Student student = new Student();
student.setName("xxx");
student.setAge(23);
student.setAddress("湖北麻城");
student.setCls("二年级");
student.setSex("男");
mockMvc.perform(post("/student").contentType(MediaType.APPLICATION_JSON)
.content(JSON.toJSONString(student))
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().is2xxSuccessful())
.andDo(document("addStudent", preprocessResponse(prettyPrint())));
}
}
这个类包含两个方法,TestApi()是用来生成例子,Test()用来生成Asciidoc的文档。生成例子用到了spring-restdocs-mockmvc,每一个API都要进行单元测试才能生成相应的文档片段(snippets),生成的结果如图:
API使用例子片段
生成完整的Asciidoc文档用到了Swagger2MarkupConverter,第一步先获取在线版本的文档并保存到文件swagger.json中,第二步把swagger.json和之前的例子snippets整合并保存为Asciidoc格式的完整文档。生成结果如图:
Asciidoc格式的文档
7.Swagger的配置
这部分可以定义一些文档相关的信息。
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.chinamobile.iot.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Student info query api")
.description("Some API to operator student information")
.termsOfServiceUrl("http://iot.10086.com/")
.version("1.0")
.build();
}
}
8.生成HTML5的文档
由于前面已经配置了maven的插件,只需要执行打包就可以生成相应的文档,如图:
最终文档