IDEA：Idea 集成 EasyYApi 插件实现接口文档的生成与更新

news2024/12/23 18:58:12

我是 ABin-阿斌：写一生代码，创一世佳话，筑一览芳华。如果小伙伴们觉得不错就一键三连吧~

在这里插入图片描述

声明：文章原文来源处：

https://blog.csdn.net/weixin_40863968/article/details/122432678
https://www.jianshu.com/p/cd915908cb96
文章目录
- 一、前言
- 二、正文
- - 1、YApi 介绍
  - - 1、YApi 平台介绍
    - 2、YApi 特性
    - 3、更新单个API
  - 2、postman方式
  - - 1、配置
    - 2、使用
  - 其他配置方式
  - - 1、第一步：
    - 第二步：

一、前言

API 这个词我相信大家都不陌生，平时的工作中也会使用到一些api管理工具，比如：YApi，swagger，postman，apidoc，showDoc，rap2等。今天主要介绍下 YApi 以及在 idea 中集成插件实现自动生成与更新 api 文档。

二、正文

1、YApi 介绍

YApi gitee 地址
YApi github 地址
YApi 官方文档地址

下面摘录部分内容来大致介绍YApi，更加深入及详细的内容请移步到上面的链接进行查看。

1、YApi 平台介绍

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API。
YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

2、YApi 特性

基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍
支持 postman，har，swagger 数据导入
扁平化权限设计，即保证了大型企业级项目的管理，又保证了易用性
类似 postman 的接口调试
自动化测试，支持对 Response 断言
MockServer 除支持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据
免费开源，内网部署，信息再也不怕泄露了

介绍完 YApi 之后，那么接下来进入正题，来看看怎么实现 Idea 与 YApi 的无缝衔接吧。

先看一下接口文档生成的效果吧：

接下来我们开始进行同步接口文档的操作：
【第一步】： 打开Idea => File => Settings => Plugins => 搜索 EasyYApi 插件并安装

在这里插入图片描述

【第二步】： 安装完成后重启Idea

【第三步】： 打开Idea => Settings => Other Settings => EasyApi 设置，在 Yapi 这块区域中中的 server表单中输入我们公司或则个人自己的 Yapi 访问地址，比如：http://127.0.0.1:8677

【第四步】： 找到对应的需要创建或者更新的controller，鼠标右键，单击 Export Yapi

第一次执行Export Yapi 会弹出一个框让我们输入Token，如下图：`

注意： 上图中的Token来源在 Yapi 服务界面【test】分组下的【test-yapi】项目设置中，【test】分组以及【test-yapi】项目都是我提前创建好的，各位可以在自己创建的项目中找到设置 => token 配置面板获取 Token

经过上面四步，我们的文档就一键同步到了 YApi , 以后如果controller中接口有变动则再次执行上文中的【第四步】即可同步最新接口到 YApi了

下面是对应的测试代码，通过代码对照这看生成的接口文档可以更加准确的了解Yapi额

controller:

/**
 * 测试 Yapi Controller
 *
 * @author maodudu
 * @version 1.0
 * @date 2022/6/19 21:16
 */
@RestController
public class TestYapiController {

    /**
     * 测试 yapi
     * @param id id
     * @return 结果
     */
    @PostMapping("/yapi/test/{id}")
    public TestYapiVO test(@PathVariable("id") String id){
        return null;
    }
}

返回结果TestYapiVO :

/**
 * 测试Yapi VO
 *
 * @author maodudu
 * @version 1.0
 * @date 2022/6/19 21:17
 */
public class TestYapiVO {
    /**
     * 名称
     */
    private String name;

    /**
     * 年龄
     */
    private Integer age;

    /**
     * 性别
     */
    private SexEnum sex;

    /**
     * 资产
     */
    private BigDecimal money;

    /**
     * 朋友列表
     */
    private List<FriendBO> friends;

    /**
     * 朋友BO
     */
    public static class FriendBO {
        /**
         * 朋友名称
         */
        private String friendName;

        /**
         * 朋友性别
         */
        private SexEnum friendSex;
    }
}

性别枚举类：

/**
 * 性别枚举类
 *
 * @author maodudu
 * @version 1.0
 * @date 2022/6/19 21:27
 */
public enum SexEnum {
    /**
     * 男
     */
    MAN,

    /**
     * 女
     */
    WOMAN,

    ;

}

3、更新单个API

在上文的基础上，如果有一个controller中有多个接口，我们只想更新其中某一个接口应该怎么操作呢？

【步骤一】： 在对应controller 鼠标右键，单击 Export Api

【步骤二】： 在弹出的面板中按需选择要更新的接口，回车即可

扩展知识点：

当我们第一次执行上文中的【第四步】同步接口到 YApi，我们输入Token之后，我们的 idea 中会对其进行保存，可通过 Idea => Settings => Other Settings => EasyApi 面板查看

注意： controller.java 文件必须要有文件注释，文件中的方法需要添加注解 @RequestMapping/@PostMapping 等任意一个，不添加无法识别方法为接口方法。就算父类方法添加了注解 @RequestMapping/@PostMapping 也无法识别，方法必须添加方法注释(接口名称就是根据方法注释生成)

2、postman方式

1、配置

在下方图片中 Postman > token 位置配置 Postman 中项目对应的 token Postman token获取Postman Integrations Dashboard

2、使用

右键Controller类 > Generate > Export Postman

其他配置方式

1、第一步：

Easy Yapi 提供了额外使用的配置文件（以设置 api 指定返回值为例）
在项目根路径下添加 yapi.config 文件，其格式为 properties 格式，官方支持的文件名及格式如下文档地址：EasyYapi

第二步：

加载外部的配置文件，可以是内外网可访问文件或本地文件
文件内容如下（两种模式二选其一，推荐使用 link 模式，与Java注释一致，可链接）

# 支持设置返回类型 package 模式（不建议）
method.return=#real_return
# 支持设置返回类型 link 模式（建议）
method.return[#real_return]=groovy:helper.resolveLink(it.doc("real_return"))