接口管理平台Yapi-最佳实践
# 背景
在开发人员开发过程中,与各方交接(前端、后端、测试、第三方平台)往往会有提供接口文档的需要
在没有在线文档应用的情况下,传统的书写md
或word
,难以简单高效的完成编写文档工作,且面临着一次修改,重新导出、上传等问题
Yapi
是目前最出色的开源接口管理平台之一,Apache Lisence
,提供了在线的接口文档管理平台、高级Mock
等工具,解放文档编写时间。
配合Easy-Yapi
插件可实现无侵入式接口文档生成
# 现有产品对比
与现有产品相比Yapi具有如下优点
- 几乎没有学习成本,私有化部署
- 支持在线编辑
- 支持
Postman
接口导入(仅支持V1) - 支持
ApiFox
、Swagger
接口导入 - 支持在线抓包导入
- 支持
Swagger2.0
格式导入、自动同步 - 配合EasyYapi idea插件零侵入式导入Controller,无需swagger注解
- 配合EasyYapi idea插件支持导入RPC接口
- 配合EasyYapi idea插件支持导出MarkDown、JSON、Postman格式文档
- 支持权限分层、多项目隔离
# 基本使用
# 主页面
# 最佳实践-配合EasyYapi插件
首先在IDEA
中下载EasyYapi
之后在任意Java
类中点击右键,便会出现对应功能
# 导出Controller到Yapi
前往任意Controller
类中,点击Export Yapi
输入Yapi
在线地址中,对应项目的token
输入之后,此时控制台显示导出成功
前往在线地址观察结果
EasyYap
i原理是识别Java doc
来创建生成的接口,上述的导出Controller
没有写任何注释,则导出时不会自动加上备注
如Controller
等接口上有Java doc
注释,则导出时加上备注,用例如下
当Controller上
有Java doc
时,导出则会产生备注
如下,该注释为idea输入/**+回车时自动生成,无需额外配置,也不需要Swagger注解
对应实体仅需按照开发规范书写Java doc
此时,生成的Yapi
文档为
# 导出RPC到Yapi
导出RPC接口,插件是默认关闭的,需要打开Settings中的开关
这里导出时默认会以RPC
接口的名字为导出项目,比如此时导出项目为contractapi
,如果你的项目名和api
名不一致则会提示你输入另外的token
(识别为2个项目)
如果想要将RPC
接口导出到同项目名的地方,加上@module
指定导出项目名即可。
如果你不想每次都书写该doc
,可以指定创建interface时的IDEA模版生成,和创建时增加作者名、创建时间同理。
# 导出为MarkDown及Postman JSON
在右键菜单选择即可
# 更多操作
更多关于EasyYapi
可识别的Java doc
可查看官网教程 (opens new window)
其实有EasyYapi
后续的内容都是可以抛弃的了,但为了全面介绍,后续支持的操作也在这里列出来相关链接
# 从Postman导入Yapi
# 从Swagger导入Yapi
这个教程写的比较全,但容易乱,总结就2步
从
http://服务域名/v2/api-docs
中获取Swagger Json
将
Json
导入到Yapi
即可
# 从ApiFox导入Yapi
同理,导出的请求为Swagger2.0
格式即可
- 01
- SpringCache基本配置类05-16
- 03
- Rpamis-security-原理解析12-13