细说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使用————接口参数注解的使用缺陷
http://www.javashuo.com/article/p-xoxiqszl-dn.html swagger2 注解说明
http://www.javashuo.com/article/p-mmfpvgjn-my.html Swagger2 关于JSONObject参数在API文档中展现详细参数以及参数说明
http://www.voidcn.com/article/p-bxgydblc-bnz.html 如何利用Swagger消除先后端分离的障碍？
http://www.javashuo.com/article/p-zvpicnqi-gr.html Swagger专题
http://www.javashuo.com/article/p-cbotzicp-gv.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 的比较
http://www.javashuo.com/article/p-ckfjeupd-gt.html Api管理工具（spring-rest-docs）