使用 EasyYapi 将接口信息一键导入Yapi

发表于 分类于

入职了新公司后，我接触到了 Yapi 这样一款强大的接口管理平台，但是相比于 Swagger，接口的创建和信息的更新在 Yapi 上显得要麻烦许多，还好在 IDEA 上有 EasyYapi 这样一款基于 Java Doc 注释生成接口信息的插件，让 Yapi 管理项目接口文档这一过程高效了很多。

安装插件

我们在 IDEA 上安装 EasyYapi 插件，可以直接搜索名字进行下载，也可以通过链接下载 EasyYapi - IntelliJ IDEs Plugin | Marketplace

导出 API

在安装完插件之后，就可以按步骤进行接口信息导出了。
首先，在项目目录中选定接口所在的文件夹，然后使用快捷键alt shift E(windows)/ctrl E(mac) , 然后选择要导出的接口，点击绿色的 ☑️ 进行导出

如果是初次使用，在导出期间需要按照提示输入 Yapi 服务的地址，以及 Yapi 项目的 token。其中项目的 token 在如下路径可以找到
看到终端出现如下输出，说明导出成功
点击链接，可以看到接口信息已经同步到 Yapi 的项目中

进阶

EasyYapi 是通过解析 Java Doc 注释来生成接口信息，如果按照 Java Doc 格式编写注释就可以在 Yapi 中补充更多的接口信息

类注释

1
2
3
4
5
6
7
8
9
10
11
/**
 * 设备控制器
 * 对设备进行控制和管理
 *
 * @author XZN1WX
 * @date 2022/05/30
 */
@RestController
@RequestMapping("/api/device")
public class DeviceController {
}

注释的第一行为分类名称，第二行为分类注释

方法注释

1
2
3
4
5
6
7
8
9
10
11
/**
 * 添加
 * 添加一台新的设备
 *
 * @param input 输入
 * @return {@link String}
 */
@PostMapping()
public Output add(@ModelAttribute Input input) {
    return new Output();
}

注释第一行是接口名，第二行是接口注释

属性注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public class Output {

    /**
     * 参数1
     */
    private String var1;

    /**
     * 参数2
     */
    private Integer var2;

    /**
     * 参数3
     */
    private Date var3;

}

属性注释中的内容对应了返回数据的备注信息

Java Doc

为了更加便捷地生成 Java Doc，可以安装 Easy JavaDoc 插件：IDEA插件系列(29):Easy Javadoc插件–快速生成javadoc文档注释_二木成林的博客-CSDN博客_idea javadoc插件

参考

  1. SpringBoot使用EasyYapi对代码0侵入实现API接口一键发布到YApi - 第422篇
  2. SpringBoot使用EasyYapi对代码0侵入实现API接口一键发布到YApi的进阶使用 - 第423篇_悟纤的博客-CSDN博客_easyyapi