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

Wang's Blog2026-10-05 12:38

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

纲要

完整使用链路：

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

#mermaid-svg-XGcJTxmfB1JwC7Mu{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XGcJTxmfB1JwC7Mu .error-icon{fill:#552222;}#mermaid-svg-XGcJTxmfB1JwC7Mu .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XGcJTxmfB1JwC7Mu .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .marker.cross{stroke:#333333;}#mermaid-svg-XGcJTxmfB1JwC7Mu svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XGcJTxmfB1JwC7Mu p{margin:0;}#mermaid-svg-XGcJTxmfB1JwC7Mu .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .cluster-label text{fill:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .cluster-label span{color:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .cluster-label span p{background-color:transparent;}#mermaid-svg-XGcJTxmfB1JwC7Mu .label text,#mermaid-svg-XGcJTxmfB1JwC7Mu span{fill:#333;color:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .node rect,#mermaid-svg-XGcJTxmfB1JwC7Mu .node circle,#mermaid-svg-XGcJTxmfB1JwC7Mu .node ellipse,#mermaid-svg-XGcJTxmfB1JwC7Mu .node polygon,#mermaid-svg-XGcJTxmfB1JwC7Mu .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .rough-node .label text,#mermaid-svg-XGcJTxmfB1JwC7Mu .node .label text,#mermaid-svg-XGcJTxmfB1JwC7Mu .image-shape .label,#mermaid-svg-XGcJTxmfB1JwC7Mu .icon-shape .label{text-anchor:middle;}#mermaid-svg-XGcJTxmfB1JwC7Mu .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .rough-node .label,#mermaid-svg-XGcJTxmfB1JwC7Mu .node .label,#mermaid-svg-XGcJTxmfB1JwC7Mu .image-shape .label,#mermaid-svg-XGcJTxmfB1JwC7Mu .icon-shape .label{text-align:center;}#mermaid-svg-XGcJTxmfB1JwC7Mu .node.clickable{cursor:pointer;}#mermaid-svg-XGcJTxmfB1JwC7Mu .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .arrowheadPath{fill:#333333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XGcJTxmfB1JwC7Mu .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-XGcJTxmfB1JwC7Mu .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XGcJTxmfB1JwC7Mu .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-XGcJTxmfB1JwC7Mu .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .cluster text{fill:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu .cluster span{color:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XGcJTxmfB1JwC7Mu .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-XGcJTxmfB1JwC7Mu rect.text{fill:none;stroke-width:0;}#mermaid-svg-XGcJTxmfB1JwC7Mu .icon-shape,#mermaid-svg-XGcJTxmfB1JwC7Mu .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XGcJTxmfB1JwC7Mu .icon-shape p,#mermaid-svg-XGcJTxmfB1JwC7Mu .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-XGcJTxmfB1JwC7Mu .icon-shape .label rect,#mermaid-svg-XGcJTxmfB1JwC7Mu .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XGcJTxmfB1JwC7Mu .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-XGcJTxmfB1JwC7Mu .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-XGcJTxmfB1JwC7Mu :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
注册并登录 YApi
添加项目

瑞吉外卖
添加分类

菜品相关 / 套餐相关
添加接口

名称 / 方法 / 路径
编辑请求参数

Header + Query/Body
编辑返回数据

导入 JSON 模板
保存并预览
后端已实现?
点运行在线测试
等待开发
状态改为已完成
数据导出

HTML/Markdown/JSON

一、YApi 是什么

定位

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

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

为什么需要它

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

载体 问题
Word/Excel 文档 易与代码脱节，改了代码忘了改文档
口头/会议约定 无据可查，人员变动即失传
聊天记录 无法检索，很快被淹没
YApi 这类管理平台 集中管理、版本可追溯、在线可测试、可导出分享

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

部署方式

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

官方推荐的部署方式：

bash 复制代码 
# 方式一：npm 全局安装（需 NodeJS + MongoDB）
npm install -g yapi-cli --registry https://registry.npm.taobao.org
yapi server
# 浏览器访问 http://localhost:9090 按向导完成部署

# 方式二：Docker 部署
docker run -d --name yapi-mongo -p 27017:27017 mongo:4.4
docker run -d --name yapi -p 3000:3000 --link yapi-mongo:mongo \
    -e YAPI_ADMIN_ACCOUNT=admin@company.com \
    -e YAPI_ADMIN_PASSWORD=ymfe.org \
    jayfong/yapi:latest

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

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

同类工具对比

工具 部署成本 特点
YApi 中（需 NodeJS + MongoDB） 国产、开源、功能全、支持 Mock
Swagger / Knife4j 低（Jar 包依赖） 代码注解驱动，与代码强同步
Postman 低（客户端） 测试强，协作需付费版
Apifox 低（SaaS） 新兴，接口+Mock+测试一体
ShowDoc 低 轻量文档，偏展示

二、创建项目与分类

注册登录

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

添加项目

右上角「添加项目」：

配置项 值 说明
项目名称 瑞吉外卖 项目标识
分组 个人空间 也可用团队分组
路径 可留空 接口 URL 的统一前缀
权限 私有 仅组长与开发者可见

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

添加分类

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

按业务模块建分类：

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

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

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

三、定义接口

基本信息

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

字段 示例 说明
接口名称 菜品分页查询 功能描述
接口分类 菜品相关接口 自动带入当前分类
请求方式 GET 分页查询用 GET
请求路径 /dish/page 与后端 @GetMapping 一致
状态 未完成 开发进度标识

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

请求参数

参数分两部分：

Header（请求头）

复制代码 
Content-Type: application/json

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

Query / Body（请求参数）

以菜品分页查询为例：

参数名 类型 是否必填 示例 说明
page Integer 必填 1 页码
pageSize Integer 必填 10 每页显示记录数
name String 非必填 鱼香肉丝 菜品名称，模糊查询

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

返回数据

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

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

粘贴：

json 复制代码 
{
  "code": 1,
  "message": "ok"
}

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

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

json 复制代码 
{
  "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 里手工敲一遍地址参数。

四、导出接口文档

操作路径

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

支持的格式

格式 用途
HTML 导出成 api.html，浏览器直接打开，离线可看
Markdown 导出成 api.md，可贴进 Wiki、Git 仓库
JSON 结构化数据，供其他工具消费
Swagger JSON 导入到其他支持 Swagger 的平台

为什么需要导出

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

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

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

导出示例

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

Markdown 版本结构大致为：

markdown 复制代码 
# 瑞吉外卖

## 菜品相关接口

### 菜品分页查询

**接口地址** `/dish/page`

**请求方式** `GET`

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| page | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页记录数 |
| name | String | 否 | 菜品名称 |

**返回数据**

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

五、批量导入接口

为什么需要导入

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

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

操作路径

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

支持的格式

格式 来源
Postman Postman 导出的集合
HAR 浏览器 Network 面板导出的请求记录
Swagger Swagger 生成的 JSON
JSON YApi 自身的导出格式

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

Swagger JSON 长什么样

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 自动分类：

txt 复制代码 
公共接口
  ├── 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 的协作关系

#mermaid-svg-cZAR4NMgr9HdChlL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-cZAR4NMgr9HdChlL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-cZAR4NMgr9HdChlL .error-icon{fill:#552222;}#mermaid-svg-cZAR4NMgr9HdChlL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-cZAR4NMgr9HdChlL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-cZAR4NMgr9HdChlL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-cZAR4NMgr9HdChlL .marker.cross{stroke:#333333;}#mermaid-svg-cZAR4NMgr9HdChlL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-cZAR4NMgr9HdChlL p{margin:0;}#mermaid-svg-cZAR4NMgr9HdChlL .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-cZAR4NMgr9HdChlL .cluster-label text{fill:#333;}#mermaid-svg-cZAR4NMgr9HdChlL .cluster-label span{color:#333;}#mermaid-svg-cZAR4NMgr9HdChlL .cluster-label span p{background-color:transparent;}#mermaid-svg-cZAR4NMgr9HdChlL .label text,#mermaid-svg-cZAR4NMgr9HdChlL span{fill:#333;color:#333;}#mermaid-svg-cZAR4NMgr9HdChlL .node rect,#mermaid-svg-cZAR4NMgr9HdChlL .node circle,#mermaid-svg-cZAR4NMgr9HdChlL .node ellipse,#mermaid-svg-cZAR4NMgr9HdChlL .node polygon,#mermaid-svg-cZAR4NMgr9HdChlL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-cZAR4NMgr9HdChlL .rough-node .label text,#mermaid-svg-cZAR4NMgr9HdChlL .node .label text,#mermaid-svg-cZAR4NMgr9HdChlL .image-shape .label,#mermaid-svg-cZAR4NMgr9HdChlL .icon-shape .label{text-anchor:middle;}#mermaid-svg-cZAR4NMgr9HdChlL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-cZAR4NMgr9HdChlL .rough-node .label,#mermaid-svg-cZAR4NMgr9HdChlL .node .label,#mermaid-svg-cZAR4NMgr9HdChlL .image-shape .label,#mermaid-svg-cZAR4NMgr9HdChlL .icon-shape .label{text-align:center;}#mermaid-svg-cZAR4NMgr9HdChlL .node.clickable{cursor:pointer;}#mermaid-svg-cZAR4NMgr9HdChlL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-cZAR4NMgr9HdChlL .arrowheadPath{fill:#333333;}#mermaid-svg-cZAR4NMgr9HdChlL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-cZAR4NMgr9HdChlL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-cZAR4NMgr9HdChlL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-cZAR4NMgr9HdChlL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-cZAR4NMgr9HdChlL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-cZAR4NMgr9HdChlL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-cZAR4NMgr9HdChlL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-cZAR4NMgr9HdChlL .cluster text{fill:#333;}#mermaid-svg-cZAR4NMgr9HdChlL .cluster span{color:#333;}#mermaid-svg-cZAR4NMgr9HdChlL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-cZAR4NMgr9HdChlL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-cZAR4NMgr9HdChlL rect.text{fill:none;stroke-width:0;}#mermaid-svg-cZAR4NMgr9HdChlL .icon-shape,#mermaid-svg-cZAR4NMgr9HdChlL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-cZAR4NMgr9HdChlL .icon-shape p,#mermaid-svg-cZAR4NMgr9HdChlL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-cZAR4NMgr9HdChlL .icon-shape .label rect,#mermaid-svg-cZAR4NMgr9HdChlL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-cZAR4NMgr9HdChlL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-cZAR4NMgr9HdChlL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-cZAR4NMgr9HdChlL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 后端写 Java 代码

加 Swagger 注解
Swagger 生成

swagger.json
导入 YApi
前后端查看

统一接口文档
前端按文档开发
后端按文档开发

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

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

六、接口文档的字段约定

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

要素 要求 反例
接口名称 动词 + 对象，见名知意 "接口1"
请求方法 严格区分 GET/POST/PUT/DELETE 全用 POST
请求路径 与后端注解一致 文档写 /dish/list，代码是 /dish/page
参数是否必填 明确标注 不标，前端猜
参数示例 给真实可用的值 给 xxx
响应字段类型 明确，特别是 Long 是否为字符串 只写"对象"
错误码含义 列出常见错误 只写"失败"
分页结构 说明 records/total/pages 让前端自己摸索

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

API 速览

功能 说明
添加项目 创建 API 项目，设置名称、分组、权限
添加分类 按业务模块对接口分组
添加接口 定义名称、方法、路径、状态
Header 参数 请求头约定，如 Content-Type: application/json
Query / Body 参数 请求参数，含类型、是否必填、示例
导入 JSON 粘贴响应样例自动解析字段结构
运行（在线测试） 真正发请求测试后端，类似 Postman
状态 未完成 / 已完成，标识开发进度
数据导出 支持 HTML / Markdown / JSON / Swagger JSON
数据导入 支持 Postman / HAR / Swagger / JSON
swagger: "2.0" Swagger 规范版本标识
tags Swagger 中的接口分组，导入后成为 YApi 分类
paths Swagger 中的接口路径与方法描述

官方文档

总结

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

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

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

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

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

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

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

相关推荐
专业程序开发源1 小时前
django新闻推荐系统70655-计算机课程设计、毕业设计
java·javascript·spring boot·后端·python·django·课程设计
jimy11 小时前
基类没有虚析构函数，基类指针删除派生类对象，行为是未定义的
开发语言·c++
迅猛龙办公室1 小时前
python获取星期字符串
开发语言·python
vx_Biye_Design1 小时前
springboot一站式旅游管理平台81037-计算机课程设计、毕业设计
java·vue.js·spring boot·后端·课程设计·express·旅游
写后端的胖头鱼1 小时前
时间复杂度 & 空间复杂度
java·数据结构·算法·时间复杂度·空间复杂度
嵌入式学习菌1 小时前
ESP32 ModbusTCP 分片缓存
java·后端·spring
vx_Biye_Design1 小时前
springboot宠物寄养服务预约与监管系统82684-计算机课程设计、毕业设计
java·vue.js·spring boot·elasticsearch·课程设计·express·宠物
程序员小杰@1 小时前
Spring Boot 常用注解分类速记
java·spring boot·后端
vx_Biye_Design1 小时前
springboot小学生英语学习APP62773-计算机课程设计、毕业设计
java·vue.js·spring boot·后端·python·学习·课程设计
热门推荐
01历年考研数学一、数学二、数学三真题试卷及答案PDF02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03如何新建文件夹？ 电脑新建文件夹的4种方法04Telegram APK 下载安装完整指南 — 2026年最新05GitHub 镜像站点06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）082026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10给AI一张“业务概念地图“：本体如何从哲学走向企业智能