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

背景

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

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

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

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

现有产品对比

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

1. 几乎没有学习成本，私有化部署
2. 支持在线编辑
3. 支持Postman接口导入(仅支持V1)
4. 支持ApiFox 、Swagger接口导入
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可查看官网教程

其实有EasyYapi后续的内容都是可以抛弃的了，但为了全面介绍，后续支持的操作也在这里列出来相关链接

从Postman导入Yapi

点击这里

从Swagger导入Yapi

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

1. 从http://服务域名/v2/api-docs中获取Swagger Json

2. 将Json导入到Yapi即可

点击这里

从ApiFox导入Yapi

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