随便一个接口文档管理工具都能秒Swagger,更别提接口文档管理工具中的佼佼者YApi了,接下来就来对比下二者的优缺点。
关于Swagger
遇到的问题
- 在想要联调接口时,如果接口还没发布甚至还没开发,则需要等待接口开发完成后才能进行联调
- 对于开发接口的人员,想要生成一份接口文档,需要先引入swagger的jar包,在定义接口时,需要额外编写大量注解及参数。在接口开发完成并发布上线前,对于其他人来说该接口定义是完全不可见的,只能等待!
- 当接口开发完成后,如果需要添加一些备注及说明,只能修改项目源代码并重新发布上线
- 接口文档的更改无法溯源,难以固化这份“标准”,一旦出现前后端接口参数不一致的问题,容易产生争执、扯皮
其他共识问题
- 代码侵入性太强、项目中需要依赖与业务无关的jar包、需要编写大量与业务无关的注解和参数,增加开发成本,降低代码可读性
- 文档的展示依赖于项目的部署启动。不便于前端脱离后端进行接口调试,降低开发效率
- 不支持全局的接口文档的统一管理和维护,没有一个文档中心
- 不支持mock数据,不便于前端调试复杂接口,影响前端开发效率及质量
- 不支持权限管理,对于接口文档的访问没有项目、角色、人员级别的权限管控
- 不支持测试人员进行接口自动化测试
- 不支持导出备份
- 添加文档备注很不方便,需要更改源代码,不能添加截图备注/不适合添加大段的备注等
- 对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse 注解用来说明返回结果,但是这个使用并不方便,而且如果返回的并不是对象的时候(如 Map),就无法实现给每一个返回字段的说明。如果将所有的返回结果都是用对象封装,然后添加注解,这又是一个非常大的工作量
- 界面巨丑,排版不人性化
YApi的特性功能
以上swagger不支持的功能yapi都可实现
- 接口文档统一可视化管理,形成接口对接规范,前后端及测试人员对一切接口的调试验证皆以Yapi文档定义为准
- 方便查找接口,不用再到处找接口,去yapi上找就行了
- 对项目零侵入、零耦合,只需编写业务代码即可,至于必要的接口注释,可使用idea模板一键生成,极大提高生产力
- 支持多种文档生成方式:导入、手动编写、根据注释自动生成
支持swagger、har、postman、json等格式文件的导入,配合idea插件,更可识别注释自动生成文档到yapi平台
- 支持导出为JSON、swaggerJOSN、Markdown、html、doc等多种文件格式,便于存档及导入到其他(自动化测试、接口管理)工具
- 丰富的插件、开放接口、钩子函数,可结合实现高度个性化功能
- 支持细粒度权限管理、第三方登录、LDAP登录
- 支持邮件通知
- 支持mock数据,真正实现前后端分离开发
- 支持自动化测试
- 支持查看接口文档变更历史
- UI界面美观、页面功能丰富、页面交互人性化
- 支持全功能私有化部署
官方文档:YApi 接口管理平台
如果打不开此文档可在host文件配置:185.199.111.153 hellosean1025.github.io
github地址:GitHub - YMFE/yapi: YApi 是一个可本地部署的、打通前后端及QA的、可视化的接口管理平台
基本信息 | YAPI | Swagger |
star数/fork数/commit数 | 21.8k / 3.8k / 5747 | 6.8k / 2k / 3978 |
初版本时间~最新版时间 | 2017.10.08~2021.06.25 | 2011.10.17~2021.06.28 |
开发语言 | 后端: koa mongoose 前端: react redux | java |
使用方 | 百度、阿里巴巴、腾讯、京东、今日头条、快手、美团、携程、去哪儿、艺龙、新浪... | Haiwei Cloud, IBM, Yelp, VMWare, Atlassian等 |
文档 | 中文文档、相关资料很多 | 英文文档完善,中文资料少 |
维护团队 | 去哪儿网 | smartbear |
总结:
Swagger优点:
- 开发语言为java,从开发语言上来讲,进行二次开发成本相对YApi较低
- 无需独立部署,只需要随应用启动即可
- 对C语言支持较好,在C语言项目无需添加注解即可生成文档
YApi缺点:
- 开发语言非java,从开发语言上来讲,进行二次开发相对Swagger较高
- 需要独立部署,不能随应用启动
更新:2022-09-06
最近发现了比二者更好用的接口文档管理工具:Apifox,有时间也写一篇对比评测