接口管理平台Yapi-最佳实践

# 背景

在开发人员开发过程中,与各方交接(前端、后端、测试、第三方平台)往往会有提供接口文档的需要

在没有在线文档应用的情况下,传统的书写mdword,难以简单高效的完成编写文档工作,且面临着一次修改,重新导出、上传等问题

Yapi是目前最出色的开源接口管理平台之一,Apache Lisence,提供了在线的接口文档管理平台、高级Mock等工具,解放文档编写时间。

配合Easy-Yapi插件可实现无侵入式接口文档生成

# 现有产品对比

与现有产品相比Yapi具有如下优点

  1. 几乎没有学习成本,私有化部署
  2. 支持在线编辑
  3. 支持Postman接口导入(仅支持V1)
  4. 支持ApiFoxSwagger接口导入
  5. 支持在线抓包导入
  6. 支持Swagger2.0格式导入、自动同步
  7. 配合EasyYapi idea插件零侵入式导入Controller,无需swagger注解
  8. 配合EasyYapi idea插件支持导入RPC接口
  9. 配合EasyYapi idea插件支持导出MarkDown、JSON、Postman格式文档
  10. 支持权限分层、多项目隔离

# 基本使用

# 主页面

# 最佳实践-配合EasyYapi插件

首先在IDEA中下载EasyYapi

之后在任意Java类中点击右键,便会出现对应功能

# 导出Controller到Yapi

前往任意Controller类中,点击Export Yapi

输入Yapi在线地址中,对应项目的token

输入之后,此时控制台显示导出成功

前往在线地址观察结果

EasyYapi原理是识别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

点击这里 (opens new window)

# 从Swagger导入Yapi

这个教程写的比较全,但容易乱,总结就2步

  1. http://服务域名/v2/api-docs中获取Swagger Json
  2. Json导入到Yapi即可

点击这里 (opens new window)

# 从ApiFox导入Yapi

同理,导出的请求为Swagger2.0格式即可