细说RESTful API之文档管理

目录

规范的接口文档管理方式有助于提高组件协同(如:前后端分离)的开发效率,对于项目的接口说明有全局的管理视角,甚至可以方便地实现对外发布。
完善的文档管理应该包含文档格式和文档管理方式这两部分,如下一一解释。

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)

posted @ 2019-07-30 00:13  2Simple  阅读(597)  评论(0编辑  收藏