细说RESTful API之文档管理

目录

• API文档格式
• 文档管理方式
  • 基于注解实现，代码和文档在一起
    • Swagger
    • Api2Doc
  • 基于API测试工具生成
    • Postman
    • rest-client
  • 独立编写文档
    • RAP
    • DOClever
    • APIDOC
    • CrapApi
• 写在最后

规范的接口文档管理方式有助于提高组件协同（如：前后端分离）的开发效率，对于项目的接口说明有全局的管理视角，甚至可以方便地实现对外发布。

完善的文档管理应该包含文档格式和文档管理方式这两部分，如下一一解释。

API文档格式

规范的API文档格式有助于理解，可以大大提高开发效率，降低不必要的沟通成本。

但是，并非需要采用统一的格式进行约束（毕竟不同的项目要求不通，不同的架构师风格也各异），有的人喜欢用Word编写，有的人却偏偏爱好Markdown语法。总之，不论采用何种格式，一定要对API接口进行完整的，清晰的描述（如：接口功能，方法定义，参数含义，返回格式等等）。

如果团队中还没有统一的API文档格式规范，可以参考蚂蚁金服API文档格式示范进行设计。

文档管理方式

RESTFul API文档管理方式（生成，维护）大致可以分为3类：

基于注解实现，代码和文档在一起

基于注解生成文档的好处是代码和文档在一起，不用单独维护一份文档；缺点也很明显，需要在业务代码中嵌入文档注解，会使得代码显得很杂乱。

基于注解方式实现文档管理的典型工具有：Swagger，Api2Doc。

Swagger

Swagger是一个很流行的RESTFul文档生成工具，但是如果需要生成一个相对规范和完善的文档，要编写太多注解，很繁琐，详见： https://swagger.io/ 。

关于使用Swagger实现对接口文档进行管理可以参考如下资源：

https://github.com/swagger-api Swagger GitHub项目官网

https://www.jianshu.com/p/33c28a65deb8 Swagger-强大的API文档工具

https://blog.csdn.net/zhangxin09/article/details/82699353 Swagger 2（Open API v3.0） Java 文档生成指南（上）

https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html 在Spring Boot项目中使用Swagger文档

https://blog.csdn.net/u014745069/article/details/80246803 Swagger使用————接口参数注解的使用缺陷

https://blog.csdn.net/xiaojin21cen/article/details/78654652 swagger2 注解说明

https://blog.csdn.net/cy921107/article/details/82761575 Swagger2 关于JSONObject参数在API文档中展示详细参数以及参数说明

http://www.voidcn.com/article/p-bxgydblc-bnz.html 如何利用Swagger消除前后端分离的障碍？

https://www.cnblogs.com/softidea/p/6226463.html Swagger专题

https://www.cnblogs.com/ceshi2016/p/10511959.html Swagger Annotation 详解（建议收藏）

Api2Doc

Api2Doc原理类似Swagger，但是基于Spring Boot框架。

目前该工具还不完善，集成1.0.2版本时报错，详见：

https://github.com/terran4j/commons/tree/master/commons-api2doc api2doc官网

基于API测试工具生成

代码和文档分离，但是不需要单独编写文档，在接口测试时就可以生成文档。

Postman

Postman就支持根据请求发布为可在线查看的API文档，如果需要考虑权限和保密性可能不适合。

http://book.crifan.com/books/api_tool_postman/website/postman_api_doc/preview_publish_api_doc.html 预览和发布API文档

rest-client

rest-client是个人开源的类似postman的REST API测试工具，可以根据API直接生成离线API文档，基于Java Swing编写的GUI界面。

https://github.com/Wisdom-Projects/rest-client

独立编写文档

独立维护API文档是最简单的方式，但是缺点也很明显，那就是可能代码与文档的同步不及时，甚至可能会出现文档是过期的。

可以使用任何喜欢的格式编写独立的API文档，根据需求可以设计成在线（目前不乏有许多在线API管理系统）或者离线（例如：可以使用Execel表格，MarkDown语法编写，甚至是Word）的格式。

如下是几款流行的基于Web的API管理工具，分别简单介绍：

RAP

官网：https://github.com/thx/RAP

RAP是阿里开源的Web接口管理工具，开源免费，支持接口自动化，MOCK数据自动生成，自动化测试，企业级管理。

虽然RAP的功能比较全，但是却不支持JSON格式的请求参数，差评。

DOClever

DOCleven是一个商业的API管理系统，官网：http://doclever.cn/controller/index/index.html。

有开源版本，详见：https://github.com/sx1989827/DOClever。

虽然DOClever号称功能非常强大而且全面，但是开源版本裁剪得实在是太精简了，不太适合拿过来直接用，基于它搞二次开发可以。

开源版安装时建议不要使用npm安装，启动时各种报错，使用源码安装没有这个问题。

# 在安装DOClever之前先安装并启动MongoDB
# 使用源码方式安装DOClevere
$ git clone https://github.com/sx1989827/DOClever.git
$ cd DOClevere
$ npm start

如果启动报错，建议使用node版本为8.11.1。

APIDOC

对于独立编写API文档的另外一个工具是APIDOC，官网：http://apidocjs.com。

相对于普通的接口文档管理工具，APIDOC走了一条比较清奇的路子。它通过接口（注意：这个接口不是业务接口，而是专门用于生成文档的接口）方式定义API，本质上也是在业务代码之外维护接口文档。

https://blog.csdn.net/soslinken/article/details/50468896 使用apidoc生成Restful web Api文档

https://blog.csdn.net/qq_27384769/article/details/78622831 apidoc使用教程-编写漂亮的api文档

CrapApi

CrapApi是目前开源产品中最满意的了，基本的API文档管理是比较全面的了，但是对于MOCK测试的支持还比较弱。

但是有利有弊，对于一款开源系统而言，核心功能已经不错了，推荐使用，详见：https://gitee.com/CrapApi/CrapApi 。

CrapApi的安装非常简单，它本身是一个传统Java Web项目，最终打包格式为war文件，所以只需要将war包放到Tomcat的webapps目录下即可访问。

值得注意是：由于CrapApi源码中的SQL脚本是使用工具导出的，里面的注释（主要是格式为/***/的注释）在某些SQL工具下可能会报错，直接删除即可。

写在最后

对于API的文档管理方式多种多样，但是没有一个方案就是一定是完美的，各自都有自己的优点和不足，主要体现在：

1.在代码中维护文档，在Java中可以通过注解来完成，最有利于维护代码和文档的一致性，但是为了生成一份相对完善的文档需要添加一堆注解，这会污染真正业务代码的简洁性，甚至会有性能损耗的缺陷；

2.独立编写文档的方式虽然不会污染业务代码，但是由于代码与文档完全分离，会隐形地增加了维护代码与文档一致性的成本；

3.相对而言，基于API测试工具生成文档的方式比较折中，但是生成文档的功能与工具本身绑定得非常紧密，很难进行私有化部署和权限管理。

实际上，无论采用哪种方式，对于文档的维护都需要一定的规章制度来硬性保证及时更新。“程序员都不喜欢写文档，却又都希望别人写文档”，这是开发者的通病，即使采用在代码中维护文档（如：Swagger）的方式，如果开发者习惯不好或者没有约定强制开发者及时维护更新文档，依然不能解决文档与代码同步的问题，毕竟这是需要人去驱动的（参数的变更，方法的增加同样需要注入对应的文档注解）。

所以，对于API文档的维护没有万能的解决方案，不论采用何种文档维护方式都必须有对应的制度强制执行，否则再好的工具使用不好依然没有意义。至于选择什么样的文档管理方式，依赖于架构师的喜好，或者根据项目本身的实际需求（如：是否需要对外发布等因素）来选定合适的方案即可，毕竟无论采用何种手段都只是达成目标的一个工具，关键在于如何高效地使用。

【参考】

https://www.jianshu.com/p/be32a38f408d API接口管理之道

https://blog.csdn.net/vimx86/article/details/78381838 接口文档管理方案

https://hacpai.com/article/1519833837647 API 管理工具 Swagger 和 RAP 的比较

https://www.cnblogs.com/minsons/p/7133095.html Api管理工具（spring-rest-docs）