前后端分离: YApi 接口管理平台的定义、导出与批量导入纲要完整使用链路YApi是什么高效、易用、功能强大的API管理平台需自行部署定义接口创建项目 → 添加分类 → 添加接口 → 配置请求参数与响应数据接口状态流转未完成 → 已完成作为开发进度的可视化标识在线测试YApi的运行功能可真正发请求类似Postman导出支持HTML、Markdown、JSON、Swagger JSON等多种格式导入支持Postman、HAR、Swagger等格式批量导入一次导入 73 个接口是否注册并登录 YApi添加项目瑞吉外卖添加分类菜品相关 / 套餐相关添加接口名称 / 方法 / 路径编辑请求参数Header Query/Body编辑返回数据导入 JSON 模板保存并预览后端已实现?点运行在线测试等待开发状态改为已完成数据导出HTML/Markdown/JSON一、YApi 是什么定位YApi是高效、易用、功能强大的API管理平台目的是为开发、产品、测试人员提供更优雅的接口管理服务。它可以帮助开发者轻松创建、发布、维护API。开发者只需利用平台提供的接口数据写入工具和简单的点击操作就能实现接口的管理。为什么需要它回顾上一篇前后端分离开发的第一步是「定制接口」。接口约定写在哪里载体问题Word/Excel文档易与代码脱节改了代码忘了改文档口头/会议约定无据可查人员变动即失传聊天记录无法检索很快被淹没YApi这类管理平台集中管理、版本可追溯、在线可测试、可导出分享有了它前后端人员看同一份接口定义开发联调时按文档验收责任清晰。部署方式YApi需要自行部署——它本质上是一个Web服务源码托管在GitHub上。官方推荐的部署方式# 方式一npm 全局安装需 NodeJS MongoDBnpminstall-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_ACCOUNTadmincompany.com\-eYAPI_ADMIN_PASSWORDymfe.org\jayfong/yapi:latest依赖关系YApi需要NodeJS运行环境与MongoDB数据存储。这是它部署成本较高的原因——不像纯静态文档那样开箱即用。课程中平台已提前部署好直接使用即可。同类工具对比工具部署成本特点YApi中需NodeJSMongoDB国产、开源、功能全、支持MockSwagger/Knife4j低Jar包依赖代码注解驱动与代码强同步Postman低客户端测试强协作需付费版Apifox低SaaS新兴接口Mock测试一体ShowDoc低轻量文档偏展示二、创建项目与分类注册登录首次使用需要注册邮箱 密码注册后登录。添加项目右上角「添加项目」配置项值说明项目名称瑞吉外卖项目标识分组个人空间也可用团队分组路径可留空接口URL的统一前缀权限私有仅组长与开发者可见创建后进入项目显示「全部接口 共 0 个」。添加分类接口多时必须分类。一个外卖平台有员工、分类、菜品、套餐、订单、购物车等多个模块接口上百个平铺会完全无法维护。按业务模块建分类瑞吉外卖/ ├── 员工相关接口 ├── 分类相关接口 ├── 菜品相关接口 ├── 套餐相关接口 ├── 订单相关接口 ├── 购物车相关接口 ├── 地址簿相关接口 └── 公共接口文件上传/下载课程演示中创建了「菜品相关接口」与「套餐相关接口」两个分类。分类粒度建议与后端Controller一一对应这样接口天然与代码模块对齐查找方便。三、定义接口基本信息进入某个分类 → 添加接口字段示例说明接口名称菜品分页查询功能描述接口分类菜品相关接口自动带入当前分类请求方式GET分页查询用GET请求路径/dish/page与后端GetMapping一致状态未完成开发进度标识提交后基本信息保存再点「编辑」补充参数细节。请求参数参数分两部分Header请求头Content-Type: application/json分页查询是GET请求、参数在URL上不需要设置Content-Type。但POST提交JSON时必须写明这是最常见的约定项。Query/Body请求参数以菜品分页查询为例参数名类型是否必填示例说明pageInteger必填1页码pageSizeInteger必填10每页显示记录数nameString非必填鱼香肉丝菜品名称模糊查询区分必填与非必填很重要——非必填参数后端要做判空处理如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里手工敲一遍地址参数。四、导出接口文档操作路径「数据管理」→「数据导出」→ 选择格式 → 导出。支持的格式格式用途HTML导出成api.html浏览器直接打开离线可看Markdown导出成api.md可贴进Wiki、Git仓库JSON结构化数据供其他工具消费Swagger JSON导入到其他支持Swagger的平台为什么需要导出离线查看。内网部署的YApi在出差、断网环境访问不了导出的静态文件可以随身带。归档与交付。项目结项交付时接口文档是必须交付物之一。二次加工。Markdown可以合并进项目文档Swagger JSON可以导入其他工具链。导出示例导出的api.html内容与平台上看到的完全一致包含接口基本信息、请求参数、返回数据。Markdown版本结构大致为# 瑞吉外卖 ## 菜品相关接口 ### 菜品分页查询 **接口地址** /dish/page **请求方式** GET **请求参数** | 参数名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | page | Integer | 是 | 页码 | | pageSize | Integer | 是 | 每页记录数 | | name | String | 否 | 菜品名称 | **返回数据** json { code: 1, message: ok } 五、批量导入接口为什么需要导入如果一个一个手工创建接口一个中等项目有上百个接口工作量巨大。如果后端已经用Swagger生成了接口描述文件就可以直接批量导入YApi。操作路径「数据管理」→「数据导入」→ 选择格式 → 上传文件 → 确认同步。支持的格式格式来源PostmanPostman导出的集合HAR浏览器Network面板导出的请求记录SwaggerSwagger生成的JSONJSONYApi自身的导出格式课程演示用的是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这些RT的字段以及data内部的嵌套结构。YApi与Swagger的协作关系后端写 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/jsonQuery/Body参数请求参数含类型、是否必填、示例导入JSON粘贴响应样例自动解析字段结构运行在线测试真正发请求测试后端类似Postman状态未完成 / 已完成标识开发进度数据导出支持HTML/Markdown/JSON/Swagger JSON数据导入支持Postman/HAR/Swagger/JSONswagger: 2.0Swagger规范版本标识tagsSwagger中的接口分组导入后成为YApi分类pathsSwagger中的接口路径与方法描述官方文档YApi官方文档https://hellosean1025.github.io/yapi/YApiGitHub仓库https://github.com/YMFE/yapiOpenAPI规范Swaggerhttps://swagger.io/specification/Swagger官方文档https://swagger.io/docs/Postman文档https://learning.postman.com/docs/总结YApi解决的是接口约定写在哪的问题。它是需自行部署的Web服务依赖NodeJSMongoDB为开发、产品、测试提供统一的接口管理服务。使用链路是「项目 → 分类 → 接口 → 参数 → 响应」。分类是必须的——上百个接口平铺会完全无法维护建议分类粒度与后端Controller一一对应。填响应结构时直接粘贴真实JSON样例最高效。YApi会自动递归解析出嵌套字段比逐行手工填表准确得多。真实样例可以从Swagger或浏览器Network面板拷贝。YApi自带在线测试能力点运行就能真发请求不必在YApi看文档再到Postman重敲一遍。导入功能是与Swagger协作的关键。后端写代码加Swagger注解 → 生成swagger.json→ 批量导入YApi课程演示一次导入 73 个接口且自动分好类。这比手工创建接口高效一个数量级且代码改了重新导出即可文档与代码天然同步。接口文档里Long类型必须标注为String。外卖平台的 19 位雪花ID经JacksonObjectMapper序列化后是字符串前端若按数字解析会踩精度丢失的坑。下一篇讲Swagger——后端工程师更常用的接口文档方案用注解写在代码里自动生成可交互文档还能在线调试。