接口文档管理工具-Postman、Swagger、RAP、DOClever,README.md
下面是关于接口文档编写工具-接口文档管理工具
在项目开发测试中,接口文档是贯穿始终的。先后端开发须要在开发前期进行接口定义并造成文档,QA在功能测试和接口测试的环节也须要依赖于这些接口文档进行测试。接口文档每每以最简单的静态文档的形态存在。然而在紧张的敏捷开发模式下,随着版本迭代,不少接口发生了变化或者被废弃,而开发几乎不会在后期去更新这种静态文档。QA人员阅读“过时”的接口文档是一件痛苦的事情,与开发的沟通成本不降反升。而这些不便于及时维护的静态文档,随着时间的推移最终无人问津。所以,咱们想要找到一种长期可维护且轻量便捷的接口文档工具。javascript
Postmanhtml
Postman是被你们所熟知的网页调试Chrome插件,咱们经常用它来进行临时的http请求调试。幸运的是,Postman能够将调试过的请求保存到Collection中。造成的Collection就能够做为一份简单有效且支持在线测试的接口文档,使用同一帐号登陆就能够作到分享和同步。对QA来讲,使用Postman进行接口测试和接口文档维护是同一件事情,测试即文档,维护成本也很低。前端
Swaggervue
“Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。”简单来讲,Swagger是一个功能强大的接口管理工具,而且提供了多种编程语言的先后端分离解决方案。Swagger主要包含了如下4个部分:java
1. Swagger能够直接嵌入项目中,经过开发时编写注释,自动生成接口文档;git
2. Swagger包含了Swagger Editor,它是使用yaml语言的Swagger API的编辑器,支持导出yaml和json格式的接口文件;github
3. Swagger包含了Swagger UI,它将Swagger Editor编辑好的接口文档以html的形式展现出来;mongodb
4. Swagger支持根据定义的接口导出各类语言的服务端或客户端代码。express
其中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是一款功能比较强大的平台,在国内好评率很高,并且产品彻底免费开源,可线下部署;同时产品更新迭代比较频繁,能够看出他们也是在用心作这个产品;
采用golang 基于Gin框架编写的在线API文档管理系统;其致力于快速解决团队内部接口文档的编写、维护、存档,以及减少团队协作开发的沟通成本。
在线体验地址
体验地址 http://apidoc.gwalker.cn/
账号: guest 密码: 123456 [注: 此体验账号为游客模式,只有只读权限] 不要改密码哟 :)
安装方法
方法一 直接使用 (推荐)
进入 https://github.com/gongwalker/ApiManager/releases
根据您的系统环境,下载 相应系统环境的可执行文件压缩包 linux ApiManager-linux-amd64.zip windows ApiManager-windows-amd64.zip mac ApiManager-darwin-amd64.zip
进入解压目录,设置数据库(创建数据库,导入db.sql) 与 配置文件(config/config.conf)
运行 ./run.sh start|stop
浏览器打开 http://your_host:8000 (账号: root 密码: 123456)
方法二 编译安装
在MySQL中创建mysql数据库,db.sql导入
修改 /config/config.ini 配置文件,修改数据库连接信息
git clone git@github.com:gongwalker/ApiManager.git 或者 git clone git@gitee.com:gongwalker/ApiManager.git
go mod vendor
go build
运行 ./run.sh start|stop
浏览器打开 http://your_host:8000 (账号: root 密码: 123456)
使用说明
系统有三个角色,超级管理、管理员、游客
超级管理员 拥有一切权限(api分类管理,api管理)
管理 可创建编辑API
游客 只能查看接口分类和接口信息 无增删改权限
默认的超级管理员 账号root 密码:123456
用到了哪些技术及项目价值
前端页面采用 layui-v2.5.6,Bootstrap v3.3.4,后端采用gin框架编写Restful Api 接口,前后端分离。
后端用到了表单校验,权限校验中间件定义,mysql数据存档,项目session可以支持cookie与redis两个储存方案
适用于中小团队api文档管理使用
可以作为一个基础角手架进行使用,快速开发。初学者可以作为熟悉gin框架学习所用
系统长什么样
以上就是小编为大家整理的接口文档编写工具-接口文档管理工具
版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。
发表评论
暂时没有评论,来抢沙发吧~