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)