如何帮助团队完成一个优秀的API文档，Swagger和Spring Rest Docs两个都是十分优秀的工具!...

背景 

 API文档是作为编写完业务代码和单元测试代码后又一个繁琐且不可或缺的工作。在前后端分离的项目中，它成为前后之间的唯一联系，表意清晰，直观易懂的API文档能协助前端更好地对接接口。API文档作为代码对外沟通的重要途径，如果文档本身的描述就存在错误，这会对工作的协作带来灾难性的打击。接下来我们探讨一下如何帮助团队完成一个优秀的API文档。

 工具 

• Swagger

  在众多的Java API生态工具当中Swagger是其中一款十分经典且强大的工具。2001年开源之后，社区更多的人加入，陆续贡献了验证、测试、UI、规范等新的组件模块。现在Swagger已经几乎成为API开发的必修工具，包括工具，规范，代码生成；包括可视化管理界面等一系列组件。

• Spring Rest Docs

  Spring Rest Docs来自Spring家族，其诞生的目的就是为了取代Spring Fox Swagger。

对比 

 Swagger和Spring Rest Docs两个都是十分优秀的工具，没有孰好孰坏。在易用性和社区的支持度，Swagger要比Spring Rest Docs更友好一些。在生成API文档的方式上Spring Rest Docs另辟蹊径，不同于市面上的大多数工作，它是通过手写文档的自动生成的方式相结合。手写文档用来提供文档中必要的背景介绍和相关内容，而自动生成文档是基于单元测试来完成。

由于自动生成的部分是基于单元测试的，可以保证文档的准确性，否则单元测试就会失败无法生成文档。这也保证了在文章开头提到的文档的准确性。这一点是我个人非常喜欢的特色。

应用 

接下来简单介绍一下Spring Rest Docs的实际应用。

简介

Spring REST Docs采用的是手写文档和自动生成相结合的形式。手写文档时可以使用 Asciidoc 和 Markdown 两种格式。推荐使用支持度更好的 Asciidoc。Spring 项目的文档也是使用 Asciidoc 来编写的。相对于更流行的 Markdown 来说，Asciidoc 的语法较为复杂，相应的功能也更强大。

Spring REST Docs依赖单元测试来产生所需的HTTP请求和响应的文档。在单元测试框架部分，Spring REST Docs支持主流的单元测试框架，包括JUnit 4、JUnit 5和TestNG。

Spring REST Docs通常是作为已有项目的一部分，与需要编写文档的REST API的模块属于同一个项目。

Maven依赖

示例接口

单元测试

文档模版

单元测试执行成功之后会在指定目录下生成接口源文档，如果没有特殊自定义，源文档的路径在：target/generated-snippets/，但是单独的源文档是没有办法直接使用的，需要自定义一套文档模版，规划好文档的排版布局，如下。

效果图

总结 

篇幅有限，关于如何在项目打包部署时生成可访问的HTML文件和其他自定义表格的内容可以参考官方网站。

相较于Swagger，Spring Rest Docs的开发成本要更大更笨重，而且需要一定的学习成本。并且在实际应用过程中，如何将将分散的源文档整合在一起，这也是相对麻烦的一点。但是笨重的同时也代表着它的功能强大。asciidoc的语法支持，代码的零侵入，以测试结果为导向的正确文档等等。也许现在应用到项目中还不够成熟，但这种以结果为单向的方式，强制执行单元测试的过程应该会成为未来的主流。

最后，欢迎对Spring Rest Docs感兴趣的小伙伴一起讨论。文中如有错误，请随时沟通指明，避免误导。

参考文档

https://docs.spring.io/spring-restdocs/docs/2.0.4.RELEASE/reference/html5

本公众号全部原创已整理成一个专栏，请在公众号里回复「测试开发」获取！