Mock 与接口文档：Swagger / Apifox 前端怎么用

更新: 7/19/2026 字数: 0 字 时长: 0 分钟

联调时最熟悉的场景:后端说"接口写好了",你打开一看字段对不上;等了半天的接口迟迟不给,前端页面卡在"假数据"里动弹不得;线上突然报错,一查是返回结构悄悄改了没通知。这些痛点的解药,基本都藏在接口文档和 Mock 这两件事里。这篇就从前端视角,讲清楚 Swagger 和 Apifox 到底该怎么用。

一、先说痛点:前端在联调里到底卡在哪

不用列太多,几条最扎心的:

• 等接口:后端还没写完,前端页面无数据可渲染,只能手写一堆假数据,后面还得删。
• 对不上:文档写的是 userName,实际返回 user_name;说好的数组结果给了个对象;可选字段没标,渲染时直接 undefined 报错。
• 改了不知道:后端偷偷调了返回结构,前端毫不知情,上线才发现页面白屏。
• 反复问:一个字段的含义、枚举值、是否必填,微信上来回问三遍,效率极低。

这些问题的本质是信息不同步。接口文档解决"接口长什么样",Mock 解决"后端没好我也能先干活",两者配合才能让前端不被后端进度绑架。

二、Swagger:主要用来"查",把接口看明白

Swagger(现在多叫 OpenAPI)是后端最常生成的在线接口文档。对前端来说,它更多是个只读的查询工具——打开一个网页地址(通常是 xxx/swagger-ui.html 或 xxx/docs),就能看到所有接口。

前端高频操作就这么几个:

• 按标签/路径找接口:接口按模块(Tag)分组,颜色区分请求方法——绿色 GET、蓝色 POST、黄色 PUT、红色 DELETE,一眼定位。
• 看请求参数:点开接口,Parameters 区列出每个参数的名字、类型、是否必填(required)、放在 query 还是 body。这是对齐字段名的第一手依据。
• 看返回结构:Responses 区展开 200 的 Example Value / Schema,能看到返回 JSON 的完整字段和类型。重点看 Schema 而不是 Example,Schema 才标了类型和必填。
• 在线试调(Try it out):点 Try it out → 填参数 → Execute,直接发真实请求,看真实返回。不用写代码就能验证"这个接口到底返回啥",比自己敲 fetch 快多了。
• 查 Model / Schema 定义:页面底部的 Schemas(旧版叫 Models)是所有数据结构的字典,嵌套对象点进去能层层展开,复杂返回体靠它理清。

一句话总结 Swagger 对前端的价值:它是后端接口的"事实说明书",联调前先在这里把字段名、类型、必填项对齐,能省掉一大半来回沟通。 缺点也明显——它基本只能查,Mock 能力弱,想拿假数据开发还得靠别的工具。

三、Apifox:查、调、Mock、导类型一站搞定

Apifox 可以理解成"Swagger + Postman + Mock 服务器"的合体。它既能看文档,又能调接口,还能自动生成 Mock 数据,是目前前端联调体验最好的工具之一。

3.1 生成并使用 Mock 数据(后端没好也能开发)

这是 Apifox 对前端最大的价值。只要接口的返回结构定义好了(哪怕后端一行代码没写),Apifox 就能按字段类型自动造出逼真的假数据。

前端高频操作:

• 拿 Mock URL 直接用:每个接口都自带一个 Mock 地址(形如 https://mock.apifox.cn/m1/xxx/接口路径),把它当成临时接口填进前端请求里,页面立刻有数据渲染。等后端好了,只需把域名换回真实环境。
• 智能 Mock 自动匹配:字段名叫 email 就给邮箱、叫 avatar 就给图片链接、叫 createdAt 就给时间——不用手写假数据,造出来的数据比自己瞎编的更接近真实。
• 自定义 Mock 规则:需要特定值(比如枚举 status 只能是 0/1/2、列表要返回 20 条)时,可以在字段上配 Mock 期望值或用 Faker 规则,精确控制假数据形态。
• Mock 异常场景:配置不同的返回(如 500、空数组、超长文本),提前测试前端的 loading、报错、兜底 UI,不用等线上才发现边界没处理。

建议:把 Mock 数据当成"契约先行"的手段。 结构定好、Mock 跑通,前后端并行开发,联调时只对逻辑不对结构,效率翻倍。

3.2 导出 TypeScript 类型(告别手写 interface)

前端最烦的活之一:照着接口文档手敲一遍 interface,字段多还容易抄错。Apifox 能直接把接口的返回结构导成 TS 类型。

• 单接口一键复制类型:在接口的返回定义处,选择"生成代码 / 复制为 TypeScript",直接得到 interface,粘进项目即用。
• 区分请求体与响应体:请求参数、响应数据可以分别导出,对应到你的 params 类型和 response 类型,前后端字段严格对齐。
• 批量生成 API 代码:配合 Apifox 的代码生成或社区的 apifox-to-ts、openapi-typescript 等工具,能按整个项目批量导出类型甚至请求函数,接口一改重新生成即可,不用手动追字段。
• 类型跟着文档走:后端改了字段类型,重新导一次,TS 立刻在编译期报错提示你哪里要改——把"上线才发现字段变了"提前到了写代码阶段。

3.3 顺手能用的其他操作

• 接口调试:和 Postman 一样填参数发请求,还能存环境变量(dev/test/prod 一键切换)、带登录 token,联调时验证真实接口很方便。
• 云端同步共享:后端更新了接口,前端拉一下就是最新的,不用再等对方发文档;评论功能可以直接在字段上问"这个枚举有哪些值"。

四、选型建议与避坑提示

怎么选:

场景	推荐	原因
后端已经用 Swagger 生成了文档	Swagger 查 + Apifox 导入	Apifox 可直接导入 OpenAPI/Swagger,拿到查、调、Mock 全套能力
团队想统一管理接口 + Mock	Apifox	一站式,Mock 和类型导出体验最好
只是临时看一眼某个接口	Swagger	打开网页就能看,零成本
后端没排期、前端要先开工	Apifox Mock	结构先行,不被后端进度卡住

避坑提示(加粗的都是踩过的坑):

• 别信 Example,要看 Schema:Swagger 的 Example 可能是手写的、过时的,Schema 才是字段类型和必填的权威来源。
• Mock 只保结构、不保业务逻辑:Mock 数据是随机造的,别拿它验证业务规则(比如金额计算、状态流转),那些必须等真实接口。
• 联调前先"锁契约":让后端把接口结构在 Swagger/Apifox 里定稿,结构一旦定了再动就要通知前端,避免偷偷改字段。
• TS 类型要跟着文档更新:导出的类型是"某一时刻的快照",后端改了记得重新导,否则类型是对的、运行时是错的,最难查。
• Mock 地址别带上线:换真实域名时全局搜一遍 mock 域名,防止把测试 Mock 地址漏到生产环境。
• 字段命名风格提前对齐:camelCase 还是 snake_case,联调开始前和后端约定死,不然前端得写一层字段转换。