Java 项目实战: 外卖平台优化-YApi接口管理平台与文档导入导出

前后端分离: YApi 接口管理平台的定义、导出与批量导入

纲要

完整使用链路：

• YApi是什么：高效、易用、功能强大的API管理平台，需自行部署
• 定义接口：创建项目 → 添加分类 → 添加接口 → 配置请求参数与响应数据
• 接口状态流转：未完成 → 已完成，作为开发进度的可视化标识
• 在线测试：YApi的"运行"功能可真正发请求，类似Postman
• 导出：支持HTML、Markdown、JSON、Swagger JSON等多种格式
• 导入：支持Postman、HAR、Swagger等格式批量导入，一次导入 73 个接口

一、YApi 是什么

定位

YApi是高效、易用、功能强大的API管理平台，目的是为开发、产品、测试人员提供更优雅的接口管理服务。

它可以帮助开发者轻松创建、发布、维护API。开发者只需利用平台提供的接口数据写入工具和简单的点击操作，就能实现接口的管理。

为什么需要它

回顾上一篇：前后端分离开发的第一步是「定制接口」。接口约定写在哪里？

有了它，前后端人员看同一份接口定义开发，联调时"按文档验收"，责任清晰。

部署方式

YApi需要自行部署——它本质上是一个Web服务，源码托管在GitHub上。

官方推荐的部署方式：

# 方式一：npm 全局安装（需 NodeJS + MongoDB）npminstall-gyapi-cli--registryhttps://registry.npm.taobao.org yapi server# 浏览器访问 http://localhost:9090 按向导完成部署# 方式二：Docker 部署dockerrun-d--nameyapi-mongo-p27017:27017 mongo:4.4dockerrun-d--nameyapi-p3000:3000--linkyapi-mongo:mongo\-eYAPI_ADMIN_ACCOUNT=admin@company.com\-eYAPI_ADMIN_PASSWORD=ymfe.org\jayfong/yapi:latest

依赖关系：YApi需要NodeJS（运行环境）与MongoDB（数据存储）。这是它部署成本较高的原因——不像纯静态文档那样开箱即用。

课程中平台已提前部署好，直接使用即可。

同类工具对比

二、创建项目与分类

注册登录

首次使用需要注册（邮箱 + 密码），注册后登录。

添加项目

右上角「添加项目」：

创建后进入项目，显示「全部接口 共 0 个」。

添加分类

接口多时必须分类。一个外卖平台有员工、分类、菜品、套餐、订单、购物车等多个模块，接口上百个，平铺会完全无法维护。

按业务模块建分类：

瑞吉外卖/ ├── 员工相关接口 ├── 分类相关接口 ├── 菜品相关接口 ├── 套餐相关接口 ├── 订单相关接口 ├── 购物车相关接口 ├── 地址簿相关接口 └── 公共接口（文件上传/下载）

课程演示中创建了「菜品相关接口」与「套餐相关接口」两个分类。

分类粒度建议与后端Controller一一对应，这样接口天然与代码模块对齐，查找方便。

三、定义接口

基本信息

进入某个分类 → 添加接口：

提交后基本信息保存，再点「编辑」补充参数细节。

请求参数

参数分两部分：

Header（请求头）

Content-Type: application/json

分页查询是GET请求、参数在URL上，不需要设置Content-Type。但POST提交JSON时必须写明，这是最常见的约定项。

Query/Body（请求参数）

以菜品分页查询为例：

区分必填与非必填很重要——非必填参数后端要做判空处理（如LambdaQueryWrapper的like(name != null, ...)），前端知道可以不传。

返回数据

YApi支持两种方式填写响应结构：

• 在表格里逐行添加字段
• 点「导入JSON」直接粘贴一段JSON样例（更方便）

粘贴：

{"code":1,"message":"ok"}

点确定后，YApi会自动解析出字段结构并填充到表格中。

对于嵌套结构，比如菜品分页的真实响应：

{"code":1,"msg":null,"data":{"records":[{"id":"1397849739276890114","name":"鱼香肉丝","categoryId":"1397844263642378242","categoryName":"川菜","price":3800,"image":"dish-xxx.jpg","status":1}],"total":24,"size":10,"current":1,"pages":3},"map":{}}

YApi会递归解析出data.records[].name这样的完整层级，前端据此定义TypeScript类型或做字段映射。

建议直接粘贴真实响应样例，比手工填表格准确得多——可以从Swagger或浏览器Network面板拷一段真实返回。

保存与预览

保存后点「预览」，可以看到完整的接口文档：基本信息 + 请求参数 + 返回数据。

前后端人员就是看这个页面开发各自的代码。

状态流转

接口开发完成后，把状态从「未完成」改为「已完成」。

这个状态是整个项目进度的可视化标识——打开项目，一眼能看出 73 个接口里有多少已完成、多少还在做。

在线测试

YApi提供「运行」按钮，可以真正发出请求测试后端接口，功能类似Postman。

课程演示时点发送报了异常，是因为后端服务没启动。后端跑起来后点发送，会真的把请求发过去并显示响应。

这个能力的价值：接口文档与测试工具合一，不用在YApi看文档、再到Postman里手工敲一遍地址参数。

四、导出接口文档

操作路径

「数据管理」→「数据导出」→ 选择格式 → 导出。

支持的格式

为什么需要导出

离线查看。内网部署的YApi在出差、断网环境访问不了，导出的静态文件可以随身带。

归档与交付。项目结项交付时，接口文档是必须交付物之一。

二次加工。Markdown可以合并进项目文档，Swagger JSON可以导入其他工具链。

导出示例

导出的api.html内容与平台上看到的完全一致，包含接口基本信息、请求参数、返回数据。

Markdown版本结构大致为：

# 瑞吉外卖 ## 菜品相关接口 ### 菜品分页查询 **接口地址** `/dish/page` **请求方式** `GET` **请求参数** | 参数名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | page | Integer | 是 | 页码 | | pageSize | Integer | 是 | 每页记录数 | | name | String | 否 | 菜品名称 | **返回数据** ```json { "code": 1, "message": "ok" } ```

五、批量导入接口

为什么需要导入

如果一个一个手工创建接口，一个中等项目有上百个接口，工作量巨大。

如果后端已经用Swagger生成了接口描述文件，就可以直接批量导入YApi。

操作路径

「数据管理」→「数据导入」→ 选择格式 → 上传文件 → 确认同步。

支持的格式

课程演示用的是Swagger JSON，导入后一次性生成 73 个接口，且自动分好类。

Swagger JSON长什么样

{"swagger":"2.0","info":{"title":"瑞吉外卖","version":"1.0"},"host":"localhost:8080","basePath":"/","tags":[{"name":"菜品管理"},{"name":"套餐管理"},{"name":"订单管理"}],"paths":{"/dish/page":{"get":{"tags":["菜品管理"],"summary":"菜品分页查询","parameters":[{"name":"page","in":"query","type":"integer","required":true},{"name":"pageSize","in":"query","type":"integer","required":true},{"name":"name","in":"query","type":"string","required":false}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/R«Page«DishDto»»"}}}}}},"definitions":{}}

这个文件完整描述了：

• swagger: "2.0"—— 规范版本
• info—— 项目信息
• host/basePath—— 服务器地址
• tags—— 接口分组（对应YApi的分类）
• paths—— 每个路径的请求方法、参数、响应

YApi解析这个文件，就能还原出全部接口。

导入结果

导入完成后，「接口」列表会多出大量接口，并按tags自动分类：

公共接口 ├── GET /common/download 文件下载 └── POST /common/upload 文件上传 分类管理 ├── POST /category 新增分类 ├── GET /category/page 分类分页查询 ├── DELETE /category 删除分类 └── PUT /category 修改分类 菜品管理 ├── POST /dish 新增菜品 ├── GET /dish/page 菜品分页查询 └── PUT /dish 修改菜品 ...

每个接口都有完整的请求参数与响应结构描述。响应里能看到code、data、map、message这些R<T>的字段，以及data内部的嵌套结构。

YApi与Swagger的协作关系

后端工程师的工作在第一步：写完Controller加注解，Swagger自动生成描述文件，导入YApi后全团队共享。

这比手工维护文档高效得多，且代码与文档天然同步——改了代码重新导出即可。

六、接口文档的字段约定

结合外卖平台项目，一份好用的接口文档应包含：

特别提醒Long类型：外卖平台所有ID是 19 位雪花ID，经JacksonObjectMapper序列化为字符串。文档里必须写明是String，否则前端按number解析会遇到精度丢失（前面第 26 篇讲过）。

API 速览

官方文档

• YApi官方文档：https://hellosean1025.github.io/yapi/
• YApiGitHub仓库：https://github.com/YMFE/yapi
• OpenAPI规范（Swagger）：https://swagger.io/specification/
• Swagger官方文档：https://swagger.io/docs/
• Postman文档：https://learning.postman.com/docs/

总结

YApi解决的是"接口约定写在哪"的问题。它是需自行部署的Web服务（依赖NodeJS+MongoDB），为开发、产品、测试提供统一的接口管理服务。

使用链路是「项目 → 分类 → 接口 → 参数 → 响应」。分类是必须的——上百个接口平铺会完全无法维护，建议分类粒度与后端Controller一一对应。

填响应结构时直接粘贴真实JSON样例最高效。YApi会自动递归解析出嵌套字段，比逐行手工填表准确得多。真实样例可以从Swagger或浏览器Network面板拷贝。

YApi自带在线测试能力，点"运行"就能真发请求，不必在YApi看文档再到Postman重敲一遍。

导入功能是与Swagger协作的关键。后端写代码加Swagger注解 → 生成swagger.json→ 批量导入YApi（课程演示一次导入 73 个接口，且自动分好类）。这比手工创建接口高效一个数量级，且代码改了重新导出即可，文档与代码天然同步。

接口文档里Long类型必须标注为String。外卖平台的 19 位雪花ID经JacksonObjectMapper序列化后是字符串，前端若按数字解析会踩精度丢失的坑。

下一篇讲Swagger——后端工程师更常用的接口文档方案：用注解写在代码里，自动生成可交互文档，还能在线调试。