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

﹏ヽ暗。殇╰゛Y 2022-05-31 01:28 402阅读 0赞

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

Postman

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

![接口文档管理工具-Postman、Swagger、RAP - 网易杭州QA - 网易杭州 QA Team][-Postman_Swagger_RAP - _QA - _ QA Team]

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打开即可以看到更美观的接口文档。

![6631879205280729966.png][]

![6631631815167585074.png][]

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

RAP

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

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

![6632051828606293252.png][]

RAP的本地搭建过程如下：

1. 本地服务准备：Tomcat、Redis、Mysql；

2. Github上下载RAP最新的war包，部署war包到Tomcat/webapps/ROOT目录下；

3. 修改数据库配置文件：ROOT/WEB-INF/classes/config.properties，修改为本地数据库的连接信息；

4. 数据库初始化：在本地数据库上执行ROOT\\WEB-INF\\classes\\database中的initialize.sql；

5. 开启tomcat、redis、mysql服务，浏览器访问 [http://localhost:8080/][http_localhost_8080]。

总结

Postman是一个测试向的API小工具，可以非常轻量地维护一份“测试记录”，适合小的测试团队自己使用并维护。Swagger丰富且独立的各个功能使得它可以被应用在各种需求下，不论是开发还是测试都可以使用这个工具，来优化自己的开发过程，进行接口文档维护、接口测试等；但Swagger的学习和接入成本相对较高，需要开发与测试的深入配合。RAP的应用范围非常明确，是一个面向开发人员自测和联调的工具性平台，它更适合以开发为核心对接口进行维护，供测试人员参考。

参考

Swagger官网： [http://swagger.io/][http_swagger.io]

Swagger Github： [https://github.com/swagger-api][https_github.com_swagger-api]

Swagger Editor在线demo： [http://editor.swagger.io/\#/][http_editor.swagger.io]

Swagger UI在线demo： [http://petstore.swagger.io/][http_petstore.swagger.io]

RAP官网： [http://rap.taobao.org/org/index.do][http_rap.taobao.org_org_index.do]

RAP Github： [https://github.com/thx/RAP/][https_github.com_thx_RAP]

[-Postman_Swagger_RAP - _QA - _ QA Team]: http://img2.ph.126.net/mjNhmZULijuGegMMGUgVgQ==/6631634014190840615.png
[6631879205280729966.png]: http://img0.ph.126.net/m_9qjcdqATSdDLLvQGHDjg==/6631879205280729966.png
[6631631815167585074.png]: http://img2.ph.126.net/GbUWeEXS2s4WRqp65kTKDw==/6631631815167585074.png
[6632051828606293252.png]: http://img1.ph.126.net/NNx18wYEPi5HOgDBCc7CLw==/6632051828606293252.png
[http_localhost_8080]: http://localhost:8080/
[http_swagger.io]: http://swagger.io/
[https_github.com_swagger-api]: https://github.com/swagger-api
[http_editor.swagger.io]: http://editor.swagger.io/#/
[http_petstore.swagger.io]: http://petstore.swagger.io/
[http_rap.taobao.org_org_index.do]: http://rap.taobao.org/org/index.do
[https_github.com_thx_RAP]: https://github.com/thx/RAP/