跳至主要內容

接口管理平台Yapi

约定规范大约 3 分钟约 949 字

接口管理平台Yapi

平台信息

Yapi介绍：国内一款优秀的接口管理平台。旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API

Yapi地址：https://yapi.tiangong.site/ （目前我们仍与创新共用一个Yapi地址）

账号密码：LDAP账号

基本使用

  1. 步骤一

    Yapi配置

    1. 创建Yapi项目

      一般我们是以某个服务为粒度去创建项目，存放该服务的全部接口，方便大家查找。

      比如我们在对应的分组创建一个”云版房需求“的新项目，对应后端服务 yunbanfang-demand-service

    img 2. 获取token

    找到项目的token，每个项目都有唯一的标识token，我们可以使用这个token来请求项目openapi，也就是我们可以通过Idea的Yapi插件去配置token，达到导出接口到项目内的目的。

    img
    img

  2. 步骤二

    Idea配置

    1. 安装EasyYapi插件

      在Idea打开 yunbanfang-demand-service 服务的 File -> Settings -> Plugins -> MarketPlace 输入 EasyYapi

      安装，并重启Idea

      img
      img

    2. 配置token

      打开 File -> Settings -> Other Settings -> EasyApi，找到Yapi 区域，复制粘贴上面获取的 token ，并配置Yapi的域名地址，点击 Apply

      img
      img

  3. 步骤三

    生成接口文档

    1. 配置 .easy.api.config 配置文件

      该配置文件用于配置一些接口公共的配置和其他特殊配置

      比如请求时接口路径加上服务的路由（服务context）？需要加上哪些固定的header？等等其他的个性化配置

      这里简要配置一下服务路由，其他的配置请自行百度。。。。。。

      • 在服务运行主方法所在目录的根目录下新建 .easy.api.config 文件

      • 配置生成的接口文档的接口路径统一加上服务的路由，这里服务的路由为 yunbanfang-demand

        class.prefix.path=/yunbanfang-demand
        img
        img

      • 也可以在Yapi文档的设置->项目配置->接口基本路径处配置

        img
        img

    2. 编写接口方法

      编写接口方法，并标注标准化类、方法注释（很重要，不然生成的接口文档的分类名和api名为controller名和method名，不能见字知意）

      EasyYapi插件会识别Java标准化注释和校验类注解，比如入参字段非空。。。。。。

    • 出参实体

      img
      img

    • 入参实体

      img
      img

    • 接口方法

      img
      img

    1. 生成Yapi接口文档

      • 方法一：在controller类，右键 -> EasyYapi -> Export Api，选择要导出的接口，按住ctrl可多选，点击 √ 生成接口文档。

      • 方法二：在controller类，右键 -> EasyYapi -> Export YApi，这样生成的是该类的所有接口。

        img
        img
        img
        img

      • 控制台输出如下则生成成功，点击下面输出的Yapi接口文档地址，直接跳转到浏览器，我们看效果。

        img
        img
        img
        img

  4. 其他支持

    1. 方法注释支持tag标签，使用tag标签可以用来标识接口的分类或者标识来自于哪个需求版本等等。

    接着上面的的方法我们修改一下

        /**
    * 这个是接口名称
    *
    * @param request 请求
    * @return 返参
    * @tag 这是标签 ##打标签
    */
    @PostMapping("/test-yapi")
    public TestYapiResponse testYapi(@RequestBody @Valid TestYapiRequest request) {
        return new TestYapiResponse();
    }

    生成后,如下图所示

    img
    img

特别说明

  • 更多的Yapi功能可以访问Yapi的官方教程文档：https://hellosean1025.github.io/yapi/documents/index.html
  • EasyYapi插件还支持接口Postman的导出
  • .easy.api.config 配置可以根据需求自定义配置请求头、文档出入参输出展示格式等等。。。
Copyright © 2025 aikero