专栏首页后端开发随笔细说RESTful API之文档管理

细说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)

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 配置tomcat限制指定IP地址访问后端应用

    1. 场景 后端存在N个tomcat实例,前端通过nginx反向代理和负载均衡。 tomcat1 tomcatN | ...

    2Simple
  • maven多模块依赖源码调试

    Maven多模块项目中,通常存在摸个模块同时依赖其他多个基础模块的情况。 在eclipse中使用run-jetty-run插件调试时,常常会出现找不到被依赖模块...

    2Simple
  • 细说java系列之泛型

    简言之,范型是Java支持在编译期进行类型检查的机制。 这里面包含2层含义:其一,可以使用范型进行类型检查;其二,在编译期进行类型检查。 那么,什么叫做在编...

    2Simple
  • 用好DocNav - Part 2

    在DocNav中可以快速查看文档章节标题而无需下载该文档。如下图所示,点击红色箭头所指的标记,即可显示文档章节标题。若要查看某章节内容,可直接点击标题名称,从而...

    Lauren的FPGA
  • 技术文档如何编写?

    谢伟
  • 文档!文档!文档!重要的事情说三遍!

    项目一期基本开发完毕,包括后台管理系统以及提供给手机端的接口还有SSO,由于奔着敏捷开发去的,文档没有过多花时间去写, 当然了文档肯定有,开发人员写的自己能看懂...

    风间影月
  • 读不懂英文文档,能写出代码不?

    作为一个开发人员,开发一个新项目,维护一个项目,想要快速的开展工作。最重要的是干什么?是阅读项目文档,没文档看代码。可见我们首要做的事情是看文档看懂文档,编程初...

    程序员互动联盟
  • 程序员既要写好代码,又要写好文档

    程序员既要写好代码,又要写好文档 作为一个长期混迹于CSDN社区的人,我对很多拥有高访问量的博主钦佩不已,特别是在参加了CSDN在举办“2014 CSDN博文大...

    用户1289394
  • 关于技术文档

    关于写技术文档,我觉得是很多做技术的同学头疼的,因为写起来确实有很多注意的细节,很花时间和精力,而反过来说,做技术的同学更头疼的是,工作中竟然没有文档说明,没有...

    jeanron100
  • 总监突然把我拉进了一个群……

    大噶好,又是我,TAPD的产品经理圆圆。 上周一上班的时候, 我发现隔壁组来了个巨帅的小哥哥。 ? 有多帅呢?可以说,是吴彦祖+金城武的那种帅。 我立马就去企...

    TAPD敏捷研发

扫码关注云+社区

领取腾讯云代金券