Yapi的安装与使用详解

Yapi的安装与使用详解

   概要

    在开发中，API 文档管理工具是开发人员必不可少的工具之一，尤其是在微服务架构和前后端分离的项目中，API 文档的管理和维护变得更加重要。常见的有Apifox、Rap2、Yapi等，本文将介绍YApi的安装部署、插件集成等，希望可以帮助大家轻松使用 YApi ，提升团队协作效率。

    一、Yapi 简单介绍

    YApi 作为一款轻量级的由美团前端团队开源的一款可视化 API 管理平台，提供了高效的接口文档管理、Mock 服务、权限控制等功能，广泛用于后端与前端协作开发中。另外，YApi 完全开源，免费使用，部署简单易上手，非常适合中小型团队或个人开发者使用。

    话不多说，下面直接开始实战，上干货~

    二、YApi安装与部署

    1. 安装环境准备

    YApi 支持 Docker 容器部署，这使得它的部署变得非常简单。你只需要准备以下环境：

• Docker 和 Docker Compose
• MongoDB 容器（YApi 依赖 MongoDB）

    2. 创建 docker-compose.yml

version: '3'

services:
  mongo:
    image: mongo:4.2
    container_name: yapi-mongo
    restart: always
    ports:
      - "27017:27017"
  yapi:
    image: registry.cn-hangzhou.aliyuncs.com/anoy/yapi
    container_name: yapi
    restart: always
    ports:
      - "3000:3000"
    environment:
      - VERSION=1.12.0
      - PORT=3000
      - ADMIN_ACCOUNT=admin@admin.com
      - ADMIN_PASSWORD=admin123
      - DB_SERVER=mongo
      - DB_PORT=27017
      - DB_NAME=yapi
    depends_on:
      - mongo

    3. 启动容器

    docker-compose up -d

    4.  访问地址

    浏览器打开：http://localhost:3000

    默认账户：admin@admin.com，密码：admin123

    三、IntelliJ IDEA 集成 EasyApi 插件

    在 IDEA 中安装 EasyApi 插件，可以更轻松地将接口文档自动推送到 YApi 平台，提高编写开发文档效率

    1. 安装插件

    打开 IDEA -> Settings -> Plugins -> 搜索并安装 “EasyApi” 插件。然后重启 IDEA 插件即可生效。

    2. 插件配置

    进入：Settings -> Other Settings -> EasyApi, 配置 YApi 的地址、项目 Token 等  

    进入:Settings -> Other Settings -> EasyApi -> BuildInConfig

    3. 使用方式

    1）在 Java Controller 上编写接口注释后，右键选择 EasyApi -> Export Api

 

    2）选择要导出文档的接口（如果要多选，则先长按 Shift 键不放，再选择指定接口），点击右上方绿色的勾进行确认，接口将被自动上传到 YApi 平台。

 

    导出成功后，idea下面run一栏中的显示如下图:

    导出完成之后，就可以发现在自己的Yapi上已经生成了新的接口文档。

    四、浏览器插件安装以及使用

    1.  安装浏览器插件

    YApi 提供了 Chrome 浏览器插件，用于与本地项目代码联动（如接口同步）

    推荐使用 Chrome插件（chrome://extensions/），下载地址：下载链接

    安装成功后如下：

 

 

 

    注意：谷歌浏览器的这个yapi插件有时候可能会失效，如果失效了的话，就移除后重新安装下插件即可恢复。当然，如果大家有其他更好的办法也可以推荐一下哦~

    2.  调试接口

    用Yapi来调试接口，使用如下：

 

    五、YApi 使用注意事项

    1. 谷歌浏览器 YApi 插件失效问题

    实际使用中可能会出现Yapi插件偶尔加载失败或同步不上的问题，通常是因为版本兼容性或浏览器安全策略导致

    建议： 将插件移除后重新加载即可

    2. yapi插件调试接口的局限

    YApi 虽然支持配置 form-data 类型的请求参数，但在调试上传图片、文件等接口时体验并不太好

    建议： 使用 YApi 插件查看接口文档即可，上传类接口调试建议使用 Postman、Apifox 等更专业的工具。

    3. Long 字段精度问题

    YApi 使用的是 JavaScript 渲染界面，而 JS 对大整数（特别是 Long 类型）支持不好，超过 2^53-1 会出现精度丢失问题，导致前端接收到的 ID 数值被截断或错误。

    建议：

•  后端统一将 Long 类型以 字符串（String）格式返回给前端；
•  YApi 中手动将字段类型设置为字符串，避免前端误解析；

    说明：在 YApi 上面调试接口的时候，long类型的入参字段，传入的时候以英文双引号 "" 包裹起来，这样传入的值精度就不会丢失。

    4. Yapi 依赖Mongo 

    YApi 依赖 MongoDB 作为底层存储，如果 YApi 所在服务器重启后，MongoDB 没有随系统自动启动，会导致 YApi 页面访问失败或接口报错。

    建议：

• 使用 Docker Compose 时，将 mongo 和 yapi 服务放在同一个编排中，自动联动；
• 重启后第一时间检查 MongoDB 状态

    六、总结

    YApi 最大的优点就是轻量、开源、免费、易于部署，适合快速开发和团队协作。

    之前我也接触过 Apifox 和 Rap2（阿里妈妈开源），这两个工具也都很不错，功能比 YApi 更强大一些，比如接口调试、文档生成、数据同步等做得更细致，但有一些小问题：

    1. Apifox

    Apifox 提供的是客户端 + 云端服务的模式，虽然功能非常全面，但很多高级功能（比如团队协作、接口自动化测试等）都限制在付费版本，个人免费版功能也不少，但企业使用成本会逐渐上来（不考虑成本的话，其实非常推荐，敲好用~）；

    个人很喜欢Apifox提供的自动化测试功能，参考下：

    自动化测试详情：

   2. Rap2

   Rap2 是阿里妈妈开源的接口平台，完全免费开源，但维护年久失修，依赖包比较老了，部署门槛也不低，使用体验上明显跟不上 YApi 和 Apifox。

   总结：相较而言，YApi 就显得“刚刚好” —— 简洁清爽、不臃肿，开源免费，配合 Docker 也能几分钟快速部署，基本能覆盖日常开发所有的接口管理需求，而且支持 Swagger/Postman 导入导出、idea集成插件、接口 Mock、权限管理等功能。

   如果你想找一个不折腾、好上手、又能快速落地的接口平台，YApi 是非常合适的选择。