SpringBoot项目生成RESTfullAPI的文档

本人所在的项目团队分为前端开发和后端开发两个子小组，前后端通过RESTfull API通信，过去一般都要用word来写API文档，随着需求的变化和开发的深入，往往还要多次更新API文档，这会给开发人员增加不少工作量。最近，项目组引入了Springfox和Spring Rest Docs来自动生成文档，本文做个记录。

1.预备知识

建议了解swagger、Asciidoc、asciidoctor-maven-plugin和SpringBoot Testing。本人觉得Asciidoc官方介绍看起来比较晦涩，因此主要参考下面两篇内容：
使用Asciidoc代替Markdown和Word撰写开发文档
AsciidocFX Asciidoc的开源编辑器，连Markdown也支持。

2.关于Springfox和Spring Rest Docs

借用官网的一句话介绍Springfox：Automated JSON API documentation for API&＃8217;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的插件，只需要执行打包就可以生成相应的文档，如图：

最终文档

源码已放到GitHub:https://github.com/quiterr/restdocs
相关博文：http://blog.csdn.net/daisy_xiu/article/details/52368920