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

上一篇 / 下一篇  2017-01-22 12:33:55

原帖来自:
http://qa.blog.163.com/blog/static/190147002201611155418810

在项目开发测试中,接口文档是贯穿始终的。前后端开发需要在开发前期进行接口定义并形成文档,QA在功能测试和接口测试的环节也需要依赖于这些接口文档进行测试。接口文档往往以最简单的静态文档的形态存在。然而在紧张的敏捷开发模式下,随着版本迭代,很多接口发生了变化或者被废弃,而开发几乎不会在后期去更新这种静态文档。QA人员阅读“过期”的接口文档是一件痛苦的事情,与开发的沟通成本不降反升。而这些不便于及时维护的静态文档,随着时间的推移最终无人问津。因此,我们想要找到一种长期可维护且轻量便捷的接口文档工具。
Postman
Postman是被大家所熟知的网页调试Chrome插件,我们常常用它来进行临时的http请求调试。幸运的是,Postman可以将调试过的请求保存到Collection中。形成的Collection就可以作为一份简单有效且支持在线测试的接口文档,使用同一账号登录就可以做到分享和同步。对QA来说,使用Postman进行接口测试和接口文档维护是同一件事情,测试即文档,维护成本也很低。
接口文档管理工具-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打开即可以看到更美观的接口文档。
 
 
Swagger Editor和SwaggerUI的本地部署十分简单,这两者都可以直接从Github上下载源码,将其部署到本地Tomcat服务器上,然后通过浏览器访问即可。官方还提供了其他几种部署方式,具体步骤在帮助文档中有详细说明,这里不再赘述。

RAP
RAP是阿里的一套完整的可视化接口管理工具,可以定义接口结构,动态生成模拟数据,校验真实接口正确性。不仅如此,RAP围绕接口定义,提供了一系列包括团队管理、项目管理、文档版本管理、mock插件等服务。
有关RAP的使用,RAP官网提供了非常详细的wiki和视频教程。与Swagger需要使用标记语言编写不同,RAP可以完全可视化地定义项目相关信息,定义接口的请求响应等等,学习成本较低。RAP还为后端开发人员提供了校验接口的功能,为前端开发人员提供了mock数据的工具等。
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/

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

TAG: 管理工具 接口

 

评分:0

我来说两句

日历

« 2024-03-02  
     12
3456789
10111213141516
17181920212223
24252627282930
31      

我的存档

数据统计

  • 访问量: 10483
  • 日志数: 2
  • 建立时间: 2017-01-22
  • 更新时间: 2017-01-22

RSS订阅

Open Toolbar