接口文档管理工具-Postman、Swagger、RAP、DOClever

在项目开发测试中，接口文档是贯穿始终的。前后端开发需要在开发前期进行接口定义并形成文档，QA在功能测试和接口测试的环节也需要依赖于这些接口文档进行测试。接口文档往往以最简单的静态文档的形态存在。然而在紧张的敏捷开发模式下，随着版本迭代，很多接口发生了变化或者被废弃，而开发几乎不会在后期去更新这种静态文档。QA人员阅读“过期”的接口文档是一件痛苦的事情，与开发的沟通成本不降反升。而这些不便于及时维护的静态文档，随着时间的推移最终无人问津。因此，我们想要找到一种长期可维护且轻量便捷的接口文档工具。

Postman

Postman是被大家所熟知的网页调试Chrome插件，我们常常用它来进行临时的http请求调试。幸运的是，Postman可以将调试过的请求保存到Collection中。形成的Collection就可以作为一份简单有效且支持在线测试的接口文档，使用同一账号登录就可以做到分享和同步。对QA来说，使用Postman进行接口测试和接口文档维护是同一件事情，测试即文档，维护成本也很低。

 

Swagger

“Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。”简单来说，Swagger是一个功能强大的接口管理工具，并且提供了多种编程语言的前后端分离解决方案。Swagger主要包含了以下4个部分：

1. Swagger可以直接嵌入项目中，通过开发时编写注释，自动生成接口文档；

2. Swagger包含了Swagger
Editor，它是使用yaml语言的Swagger API的编辑器，支持导出yaml和json格式的接口文件；

3. Swagger包含了Swagger
UI，它将Swagger Editor编辑好的接口文档以html的形式展示出来；

4. Swagger支持根据定义的接口导出各种语言的服务端或客户端代码。

其中1和4是更加面向开发的内容，开发团队要有自动生成文档的需求，在开发和自测中遵循前后端分离。而2和3是相对可以独立出来的、可供QA人员参考的接口文档管理方案，也是我们主要关注的部分。

Swagger提供了Swagger
Editor和Swagger UI的在线demo，如下图。可以看出，Swagger可以完整地定义一个接口的内容，包括各个参数、返回值的具体结构、类型，Swagger
Editor可以实时进行编辑并在线调试。编辑好的API可以导出为json文件，使用Swagger UI打开即可以看到更美观的接口文档。

 

Swagger Editor和SwaggerUI的本地部署十分简单，这两者都可以直接从Github上下载源码，将其部署到本地Tomcat服务器上，然后通过浏览器访问即可。官方还提供了其他几种部署方式，具体步骤在帮助文档中有详细说明，这里不再赘述。

RAP

RAP是阿里的一套完整的可视化接口管理工具，可以定义接口结构，动态生成模拟数据，校验真实接口正确性。不仅如此，RAP围绕接口定义，提供了一系列包括团队管理、项目管理、文档版本管理、mock插件等服务。

有关RAP的使用，RAP官网提供了非常详细的wiki和视频教程。与Swagger需要使用标记语言编写不同，RAP可以完全可视化地定义项目相关信息，定义接口的请求响应等等，学习成本较低。RAP还为后端开发人员提供了校验接口的功能，为前端开发人员提供了mock数据的工具等。

 

DOClever

DOClever是一个可视化接口管理工具
,可以分析接口结构，校验接口正确性， 围绕接口定义文档，通过一系列自动化工具提升我们的协作效率。DOClever前后端全部采用了javascript来作为开发语言，前端用的是vue+element UI，后端是express+mongodb，这样的框架集成了高并发，迭代快的特点，保证系统的稳定可靠。

 

DOClever产品功能如下：

· 可以对接口信息进行编辑管理，支持
get,post,put,delete,patch 五种方法，支持 https 和 https 协议，并且支持 query，body，json，raw，rest，formdata 的参数可视化编辑。同时对 json 可以进行无限层次可视化编辑。并且，状态码，代码注入，markdown 文档等附加功能应有尽有。

· 接口调试运行，可以对参数进行加密，从md5 到 aes 一应俱全，返回参数与模型实时分析对比，给出不一致的地方，找出接口可能出现的问题。如果你不想手写文档，那么试试接口的数据生成功能，可以对接口运行的数据一键生成文档信息。

· mock 的无缝整合，DOClever 自己就是一个 mock 服务器，当你把接口的开发状态设置成已完成，本地 mock 便会自动请求真实接口数据，否则返回事先定义好的 mock 数据。

· 支持 postman，rap，swagger 的导入，方便你做无缝迁移，同时也支持 html 文件的导出，方便你离线浏览！

· 项目版本和接口快照功能并行，你可以为一个项目定义 1.0，1.1，1.2 版本，并且可以自由的在不同版本间切换回滚，再也不怕接口信息的遗失，同时接口也有快照功能，当你接口开发到一半或者接口需求变更的时候，可以随时查看之前编辑的接口信息。

· 自动化测试功能，目前市面上类似平台的接口自动化测试大部分都是伪自动化，对于一个复杂的场景，比如获取验证码，登陆，获取订单列表，获取某个特定订单详情这样一个上下文关联的一系列操作无能为力。而 DOClever 独创的自动化测试功能，只需要你编写极少量的 javascript 代码便可以在网页里完成这样一系列操作，同时，DOClever 还提供了后台定时批量执行测试用例并把结果发送到团队成员邮箱的功能，你可以及时获取接口的运行状态。

· 团队协作功能，很多类似的平台这样的功能是收费的，但是 DOClever 觉得好东西需要共享出来，你可以新建一个团队，并且把团队内的成员都拉进来，给他们分组，给他们分配相关的项目以及权限，发布团队公告等等。

 

DOClever 开源免费，支持内网部署，很多公司考虑到数据的安全性，不愿意把接口放到公网上，没有关系，DOClever 给出一个方便快捷的解决方案，你可以把平台放到自己的内网上，完全不需要连接外网，同时功能一样也不少，即便是对于产品的升级，DOClever 也提供了很便捷的升级方案！

总结

Postman是一个测试向的API小工具，可以非常轻量地维护一份“测试记录”，适合小的测试团队自己使用并维护。Swagger丰富且独立的各个功能使得它可以被应用在各种需求下，不论是开发还是测试都可以使用这个工具，来优化自己的开发过程，进行接口文档维护、接口测试等；但Swagger的学习和接入成本相对较高，需要开发与测试的深入配合。RAP的应用范围非常明确，是一个面向开发人员自测和联调的工具性平台，它更适合以开发为核心对接口进行维护，但目前基本不在维护。DOClever是一款功能比较强大的平台，在国内好评率很高，而且产品完全免费开源，可线下部署；同时产品更新迭代比较频繁，可以看错他们也是在用心做这个产品；