使用 docker-compose 部署和使用 Yapi

随着时间的推移，一个公司的项目或系统会比较多，对内对外提供的 api 接口也比较多，为了能够对 api 接口文档进行统一维护，方便不同的人员（项目经理、产品经理，开发人员）进行查阅，很有必要搭建一个 api 接口文档管理系统。

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

本篇博客将介绍如何快速进行搭建 Yapi ，在 IDEA 开发工具安装 EasyYapi 插件，向 Yapi 系统发布接口文档。

Yapi 的源代码地址：https://github.com/YMFE/yapi

Yapi 的帮助文档地址：https://hellosean1025.github.io/yapi

EasyYapi 插件的官网地址：https://easyyapi.com/index.html

一、搭建 Yapi 系统

我的 CentOS7 虚拟机 ip 地址是 192.168.136.128，已经安装好了 docker 和 docker-compose

Yapi 使用 mongodb 作为数据库，由于 Yapi 一般在公司内部使用，搭建单机版 mongodb 即可满足需求

首先在 CentOS7 中创建目录 /app/yapi，里面创建子目录 mongodb_data 和 docker-compose.yml 文件

编写 docker-compose.yml 文件内容如下：

version: "3.5"
services:
  mongodb:
    container_name: mongodb
    image: mongo:latest
    restart: always
    ports:
      - 27017:27017
    environment:
      - MONGO_INITDB_ROOT_USERNAME=jobs
      - MONGO_INITDB_ROOT_PASSWORD=123456
    volumes:
      - /app/yapi/mongodb_data:/data/db
    networks:
      - yapi_net
    # 增加启动参数，--auth，表示连接 mongodb 需要用户名和密码
    command:
      - "--auth"
 
  yapi:
    image: jayfong/yapi:latest
    container_name: yapi
    restart: always
    ports:
      - 3000:3000
    environment:
      # 随便设置一个账号（账号是邮箱的格式）
      - YAPI_ADMIN_ACCOUNT=jobs@yapi.com
      # 设置账号的密码
      - YAPI_ADMIN_PASSWORD=jobs666
      # 禁用注册功能
      - YAPI_CLOSE_REGISTER=true
      # 设置连接 mongdb 的服务器地址，可以使用容器内部的 mongodb 服务名称
      - YAPI_DB_SERVERNAME=mongodb
      - YAPI_DB_PORT=27017
      - YAPI_DB_DATABASE=yapidb
      - YAPI_DB_USER=jobs
      - YAPI_DB_PASS=123456
      - YAPI_DB_AUTH_SOURCE=admin
      #- YAPI_DB_CONNECT_STRING="mongodb://jobs:123456@mongodb:27017/yapidb?authSource=admin"
      # 禁用发送邮件的功能
      - YAPI_MAIL_ENABLE=false
      # 禁用 LDAP 登录功能
      - YAPI_LDAP_LOGIN_ENABLE=false
      # 不使用任何插件
      - YAPI_PLUGINS=[]
    networks:
      - yapi_net
    depends_on:
      - mongodb
 
networks:
  yapi_net:
    driver: bridge

不需要在 mongodb 中提前创建数据库，启动服务后会自动创建并初始化所配置的 mongodb 数据库、以及相关表和数据。

最后运行 docker-compose up -d 命令启动服务，访问 http://192.168.136.128:3000 即可

点击【登录/注册】按钮，使用上面 docker-compose.yml 中初始化的 admin 角色的账号 jobs@yapi.com 密码 jobs666 进行登录。

我创建了一个名称叫作 fileupdown 项目，新建项目时，权限只能选择【私有】，创建完成后，可以在界面中设置为【公开】。

点击项目 fileupdown 图标，在设置选项卡界面，在底部可以把该项目的权限设置为【公开】。

另外在 token 配置界面中，可以看到 fileupdown 项目的 token 值，这个我们下面需要使用，如下所示：

二、IDEA 安装和使用 EasyYapi 插件

可以在 IDEA 的【设置】-->【插件】中的 Marketplace 中搜索 EasyYapi，然后进行安装，下图是我安装后的结果

如果网络不好，搜索不到，或者 IDEA 是在内网，无法联网，可以上 EasyYapi 官网下载插件，进行离线安装

离线安装的参考文档地址为：https://easyyapi.com/documents/installation.html

注意：离线安装的话，需要安装与自己的 IDEA 开发工具版本匹配的 EasyYapi 插件版本

我使用 IDEA 打开了之前自己开发的一个 Demo 项目，名称叫做 springboot_fileupdown，随便开发一个 controller 接口文件，在文件的任意地方通过右键菜单选择【EasyApi】，然后选择二级菜单【Export Yapi】

在弹出的框内，填写上已经部署成功的 Yapi 系统的访问地址：http://192.168.136.128:3000

然后又会弹出一个框，把 Yapi 系统的 fileupdown 项目的 token 字符填写一下，最后点击确定，发布接口到 Yapi 系统中。

发布后的效果如下：

在代码如果给 controller 以及里面的每个方法和参数，添加上注释，然后再发布就会展示注释的内容，代码如下所示：

/**
 * 文件上传下载接口
 */
@RestController
@RequestMapping("/updown")
public class UpdownController {
 
    /**
     * 获取已经上传的文件列表
     */
    @GetMapping("/list")
    public Result<List<String>> getFileList() {}
 
    /**
     * 上传文件接口
     * @param file 选择一个文件
     */
    @PostMapping("/upload")
    public Result<String> upload(MultipartFile file) {}
 
    /**
     * 下载文件接口
     * @param name 要下载的文件名称
     */
    @GetMapping("/download")
    public void download(String name, HttpServletResponse response) {}
 
    /**
     * 删除文件接口
     * @param name 要删除的文件名称
     */
    @GetMapping("/delete")
    public Result<String> delete(String name) {}
 
    /**
     * 清空上传的文件
     */
    @GetMapping("/clear")
    public Result<String> clear() {}
}

再次发布到 Yapi 系统中，效果如下所示：

当然我们也可以从 swagger 和 postman 中导出 api 文件，然后导入到 Yapi 系统中，这里就不再演示了。

有关 Yapi 的所有功能的用法，可以参考 Yapi 的在线帮助文档 https://hellosean1025.github.io/yapi