Swagger、Rap与Yapi接口管理
一、前言
随着项目的规模上升,投入的人力、资源与开发方式都有着很大的变化,大型的项目一般都会采用前后端分离的开发模式,在这种方式中,如何更好的协作工作是提高效率的关键。
在前后端交互中,主要核心的是接口对接与联调,一个好的接口管理工具必不可少,本文也是基于此对目前使用的几种工具进行分析。
在目前工作的一段时间中,基于公司现在使用的 Rap 接口管理工具存在的一些问题,与现在市面上其他常用的接口管理工具或者平台进行对比,推荐可以转用 Yapi 接口管理平台。
- Swagger 开源接口框架
- YApi 接口管理平台
- Rap 接口管理工具
二、Swagger 开源接口框架
相比其他,其实不应该将Swagger归结在接口管理工具中,本文的主要对象也不是Swagger,所以只做简单的了解。Swagger在整个API生命周期中都会存在,是一种编写OpenAPI的规范,从接口设计、文档到测试和部署都会存在,能够快捷生成API doc,依托于对应服务提供测试功能(每一个服务都可以通过url查看对应的Swagger接口文档),如果不做控制,所有人可见。
Swagger 通过集成框架,用其中的各种注解来对接口中的请求路径、请求方式、请求参数、响应参数等进行说,生成的接口文档与项目代码息息相关,可以说接口即是文档,文档即是接口。
核心
- 提供一个编写API文档的规范,成为OAS,在规范中明确API的格式和一些编写要素;
- 提供相关的工具,对API文档的编写提供辅助;
- 提供对各种流行语言和框架的集成,例如集成SpringMVC、SpringBoot的springfox框架。
开源框架
- Swagger Editor
- 基于浏览器的编辑器,您可以在其中编写OpenAPI规范。
- Swagger Codegen
- 从 OpenAPI 规范生成服务器存根和客户端库。
- Swagger UI
- 将 OpenAPI 规范呈现为交互式 API 文档。
- Swagger UI Configuration
- 可定义多种UI风格的API文档及页面
使用文档
- Swagger配置详解 - 打盹的闲鱼 - 博客园 (cnblogs.com)
三、YApi 与 Rap
在接口管理,以及前后端对接方面,相比Swagger,其他的方式更加灵活,多样,在中大型前后端分离项目大都选择接口管理工具或者平台来进行管理,就目前使用过的 YApi 和 Rap 说一下使用感受(也推荐正在使用Rap的转用YApi)。
综合多个维度进行对比分析优势劣势,主要包含以下几方面:
1、接口管理工具本身功能点分析;
2、在项目团队、人员规模不断上升的协同工作方面分析;
3、从 Rap 转用 Yapi 的成本与可行性方案。
演示环境:YApi-高效、易用、功能强大的可视化接口管理平台 (smart-xwork.cn)http://yapi.smart-xwork.cn/
Rap接口转Yapi,swagger:GitHub - xuzhou-99/rap2Yapi: rap接口迁移yapi接口管理平台,支持rap导出转yapi json,rap2导出转swagger json,rap2导出转yapi jsonrap接口迁移yapi接口管理平台,支持rap导出转yapi json,rap2导出转swagger json,rap2导出转yapi json - GitHub - xuzhou-99/rap2Yapi: rap接口迁移yapi接口管理平台,支持rap导出转yapi json,rap2导出转swagger json,rap2导出转yapi jsonhttps://github.com/xuzhou-99/rap2Yapi
四、Rap 与 Yapi 多维度对比分析
(一)功能点分析
主要从基础功能、拓展支持、成本以及开源社区等多方面分析:
YApi |
Rap |
|
文档管理 |
√ |
√ |
Mock Server |
√ |
√ |
接口测试 |
√ (Chrome 插件) |
× |
自动化测试 |
√ |
× |
插件 |
√ |
× |
开源 |
√ |
√ |
内网部署 |
支持 |
支持 |
部署难度 |
中 |
高 |
学习成本 |
低 |
低 |
支持导入 |
√ (swagger, postman, har,json) |
√ |
支持导出 |
√ (html,markdown,json,swagger) |
√ (html) |
备份迁移 |
支持 (导入导出、项目复制) |
支持 (备份方式导入导出) |
权限管理 |
√ |
√ |
页面 |
美观 |
简洁 |
并发操作 |
支持多人同时编辑 (单个接口锁定) |
不支持 (整个项目锁定) |
社区 |
活跃 (文档多) |
Rap2 活跃 (文档少) |
(二)协同工作分析
1、接口文档
除了在开发过程中需要对接口进行管理,在其他环节也会需要对接口进行交流、沟通,例如说开放的api接口、对于第三方支持的接口等,接口文档功能也必不可少。只要是个此类的工具都会支持,多的是考虑对于接口管理是否支持导入、导出,与其他接口管理兼容程度、文档支持的类型等等。
对比:YApi 优,文档类型丰富,对其他工具、文档格式兼容性好
YApi
- 支持接口管理
- 支持 swagger,postman,har,json 格式文档导入
- 通过插件支持 Rap 接口导入
- 支持导出 html,markdown,json,swagger-json 格式的接口文档
Rap
- 支持接口管理
- 支持导出 Word 格式接口文档
2、权限管理
接口管理的安全不可忽视,每个项目的接口管理只有对应的成员可以进行编辑、管理。
对比:管理维度不同,都支持
YApi
- 通过分组管理项目,分组可以进行人员管理,存在分组组长
- 通过项目管理接口,项目可以进行人员管理,存在项目组长
Rap
- 通过团队管理业务线,团队可以进行人员管理,管理员操作
- 通过业务线管理分组
- 通过分组管理项目
- 通过项目管理接口,项目可以进行人员管理,管理员操作
3、开发协同
随着团队的项目规模、人员规模等不断扩大,项目的管理与开发模式也需要不断的调整。在中大型团队中,协同工作是一件非常考验团队的方面,一款优秀的接口管理工具必然能够提供更加高效的协同。Rap 在项目管理中对于协同工作的支持特别不友好,这也是推荐转用 Yapi接口管理平台 的主要原因。
对比:YApi 优,多人团队协同工作,这一点毋庸置疑
YApi
- 支持前端 Mock,生成合适的接口参数,方便前端验证接口
- 支持后端通过插件进行接口测试(仅Chrome + cross-request 插件)
- 支持配置多环境进行接口测试(同一个项目支持个人、开发环境、测试环境等多环境,只要切换就行)
- 支持多人协同工作,对同一项目接口进行管理、编辑(内部加锁,页面操作无感)
- 支持接口协同状态:未完成+已完成 + 自定义Tag(设计中、开发中、待提测、已发布)
- 通过插件支持接口变动通知,前端、后端可以实时知道接口开发状态
- 提供操作日志
Rap
- 支持前端 Mock,生成合适的接口参数
- 不支持在线接口测试,需要其他工具测试接口
- 不支持多人协同工作,对同一个项目同一时间只能有一人编辑(项目级别加锁,几个人一起影响较小,但是规模上升时,一个业务项目十几个、几十个一起开发就会严重受限)
- 不支持开发状态管理(接口开发进度需要人员主动通知)
- 提供接口版本记录
4、使用与插件
除了做好核心的接口管理工作,现在的接口管理工具很多都会提供更多的拓展服务,本点主要包含用户管理、第三方插件与其他(基于内网部署,私有团队)。
对比:差异不大;YApi插件丰富,支持更多拓展功能
YApi
- 通过服务注册账号
- 支持通过插件实现 SSO、CAS、gitlab、oauth2.0 、企业微信 等登录方式
- 支持通过插件实现对接口变动进行通知
- 支持通过插件代码生成接口
Rap
- 通过服务注册账号
(三)Rap转Yapi成本及可行性分析
1、服务部署
在使用过程中,主要关注的有以下几点:成本开销,部分的接口管理工具是收费的,也有开源的工具,如果不是特别有钱的话,基本上都考虑支持私有部署,开源免费的产品。
Rap的部署需要的资源环境要比Yapi多,而对于Yapi的部署,只需要 nodejs 7.6+、mongodb 2.6+,并支持可视化(yapi-ci)部署配置,简单的只需要10分钟既可部署完成。mongodb也是公司产品用的主要数据库之一,可以兼用。
2、Rap转Yapi
得益于Yapi本身的优秀,它有着活跃的社区和丰富的插件可以选择,支持各种样式的接口导入,通过使用插件,可以实现Rap已有接口快速的导入到Yapi并形成项目。
现有插件:yapi-plugin-import-rap(wxxcarl/yapi-plugin-import-rap: a yapi plugin for import projects from rap (github.com)),以项目维度来进行Rap转Yapi接口。
五、YApi 接口管理平台
(一)相关资源
- GitHub:YMFE/yapi: YApi(github.com)
- 使用文档:YApi 接口管理平台 (smart-xwork.cn)
(二)主要模块介绍
1、项目管理
2、接口管理
3、权限控制
4、接口测试
六、Rap2 接口管理工具
(一)相关资源
- GitHub:
- thx/RAP: Web接口管理工具
- thx/rap2-delos: RAP第二代
- 使用文档:Rap 用户使用手册
(二)主要模块介绍
1、项目管理
2、接口管理
3、权限控制
RAP上支持对接口按照 团队、业务线、分组 三个层级管理。通过顶部导航栏“团队”TAB可以进行创建和切换。
(1)项目权限
操作 |
游客 |
项目开发者 |
项目 |
管理员 |
浏览公开项目和接口 |
√ |
√ |
√ |
√ |
浏览私有项目和接口 |
√ |
√ |
√ |
|
新建项目 |
√ |
√ |
√ |
|
编辑项目 |
√ |
√ |
√ |
|
删除项目 |
√ |
√ |
||
新增接口 |
√ |
√ |
√ |
|
编辑接口 |
√ |
√ |
√ |
|
删除接口 |
√ |
√ |
√ |
(2)层级管理
操作 |
分组 |
业务线 |
团队 |
管理员 |
创建团队 |
√ |
|||
修改团队 |
√ |
|||
删除团队 |
√ |
|||
创建业务线 |
√ |
√ |
||
修改业务线 |
√ |
√ |
||
创建分组 |
√ |
√ |
||
修改分组 |
√ |
√ |
||
删除分组 |
√ |
√ |
||
创建项目 |
√ |
√ |
||
修改项目 |
√ |
√ |
||
删除项目 |
√ |
√ |
参考文档
- Swagger Documentation
- Swagger详细了解一下(长文谨慎阅读) - 腾讯云开发者社区-腾讯云 (tencent.com)
- user_manual_cn · thx/RAP Wiki (github.com)
- YApi-教程
- YApi、RAP等其他接口管理工具的优缺点? - 知乎 (zhihu.com)
- 六大接口管理平台,总有一款适合你的 - 知乎 (zhihu.com)
- API 管理工具 Swagger 和 RAP 的比较 - 简书 (jianshu.com)
Swagger、Rap与Yapi接口管理相关推荐
- Java后端接口自动生成神器 -- EasyYapi插件(Yapi接口管理工具在IDEA里的插件)
Java后端接口自动生成神器 – EasyYapi插件(Yapi接口管理工具在IDEA里的插件) 一.先看效果 1.生成yapi文档的效果 2.生成postman格式数据并导入接口测试类后的效果(如p ...
- Swagger、Yapi接口管理服务_SE
文章目录 Swagger 介绍 使用方式 查看接口文档 常用注解 问题说明 注解介绍 注解测试 Yapi 介绍 使用 准备 定义接口 导出接口文档 导入接口文档 Swagger 介绍 官网:https ...
- YApi接口管理平台远程代码执行漏洞(含批量POC)
0x00简介 YAPI是由去哪儿网移动架构组(简称YMFE,一群由FE.iOS和Android工程师共同组成的最具想象力.创造力和影响力的大前端团队)开发的可视化接口管理工具,是一个可本地部署的.打通 ...
- yapi 接口管理平台手册
文章目录 前言 背景.现状.意义 mock测试 yapi 基于项目的管理 API接口管理 mock 服务器 使用 服务端使用路径 客户端使用路径 参考资料 前言 本篇旨在让相关开发人员理解引入 y ...
- 搭建YApi接口管理平台+IDEA插件easyYapi一键生成接口动态发布到YApi平台
文章目录 一.简介 二.YApi搭建 1.准备 2.可视化部署 3.浏览器访问 4.新建项目 5.获取项目的token 三.IDEA插件easyYapi 1.安装easyYapi 2.配置连接YApi ...
- 搭建 yapi 接口管理平台
yapi 是一款去哪儿的接口管理软件,总之很强大,下面开始记录搭建过程 1:首先是下载 node 源码.安装node环境 wget https://nodejs.org/dist/v10.15.3/n ...
- 安装YApi 接口管理平台
背景 在前后端分工合作的项目中,会出现一种尴尬局面.在项目进入研发阶段初期,前端和后端人员约定api接口,请求参数,返回参数.往往两端人员都在纠结模拟数据应该由谁来负责,但无论谁负责也好,必然会对项目 ...
- 部署 YApi 接口管理服务
安装 Node curl -sL https://rpm.nodesource.com/setup_8.x | bash - yum install -y nodejs 安装 MongoDB vi / ...
- YApi 接口管理平台
参考:https://blog.csdn.net/rcjjian/article/details/79968836 https://blog.csdn.net/kxzhaohuan/article/d ...
- yapi 权限_win10 x64下从0开始搭建YApi可视化接口管理平台
YApi 是高效.易用.功能强大的 api 管理平台,旨在为开发.产品.测试人员提供更优雅的接口管理服务.可以帮助开发者轻松创建.发布.维护 API,YApi 还为用户提供了优秀的交互体验,开发人员只 ...
最新文章
- 低版本jdbc连接高版本oracle,转:oracle11g的JDBC连接 URL和之前的版本有一定的区别...
- 微信公众平台开发入门教程(三)消息类型讲解
- 成功解决return tf.nn.softmax(x, axis=axis) TypeError: softmax() got an unexpected keyword argument 'axis
- Scala父类构造方法
- SpringBoot 配置错误页
- razor java,如何在Razor中声明局部变量?
- 作业一——根据成绩计算出至少需要发多少奖金才能让所有的组满意。
- php scrscriptipt,xss跨站脚本攻击 (初级-中级-高级)
- android 关掉屏幕旋转,防止在Android中屏幕旋转时解除对话框
- live555保存文件的问题
- 24小时改变你的人生【转】
- Junit单元测试的基本编码步骤
- Pikachu漏洞靶场 敏感信息泄露
- 100m光纤测速多少正常_100m宽带wifi测速多少为正常
- php的toast,toast提示是什么
- 优雅草开源系统-YYC优雅草蜻蜓Q系统前端文件目录说明-----搭配后端
- 关于苹果AR/VR专利新闻的一次超详细探索!
- 重庆科技学院计算机考研资料汇总
- 人工智能——归结演绎推理
- 关于 X509Certificate2 找到文件路径的问题
热门文章
- nicstat-网络流量统计利器
- Java 将控制台输出打印 输出到本地文件
- MSVC2019 QT6 环境下的 C++ 中文编程实现(一)
- 各种电脑/软件/生活/音乐/动漫/电影技巧汇总,你肯定能发现你需要的使用技巧,你的生活绝对会因此简化很多,具体操作见本专栏相关文章或点击链接
- 尚硅谷java学习笔记第五天(数组上)
- python中iter是什么意思_iter的用途是什么?
- php script是什么,script是什么意思
- python找出大写字母_在大写之前提取元素 - python
- 人工智能研究中心快递柜——代码分析十三
- win7 桌面图标 计算机 灰色,win7系统桌面不显示计算机图标的解决方法