
使用 Apifox 的同学,这个 MCP 你一定要装
使用 Apifox 的同学,这个 MCP 你一定要装
1、引言
以前写接口,我一直依赖 Swagger 生成文档。代码里加好注解、写清说明,大部分文档工作在 IDE 里顺手就搞定了,相信不少同学和我一样。
但最近由于团队协同的需要,所有接口文档统一要求放到 Apifox 管理。这下麻烦来了:接口代码写完,还得切到 Apifox 手动写文档——接口摘要、参数类型、是否必填、字段释义、示例值、返回结构体…… 一项一项复制粘贴。
更头疼的是后续迭代,需求改个三五轮,只要没人持续盯着同步,接口文档和代码分道扬镳则是必然的。等前端联调或者新人接手,文档早就过时了,纯纯无效文档。
试过让 AI 帮忙整理接口信息?可以是可以,但之前没法直接连通 Apifox,AI 整理完,最后还是要我们手动复制粘贴进去,省不了多少事。
直到发现 Apifox 官方内测新版 Apifox MCP,相当于打通了 AI 和 Apifox 项目的通道,直接读写接口资产,这个痛点才算有了合适的解法。

本篇不展开讲具体的操作细节,结合日常开发,聊聊几个真正能落地、能帮我们减负的实用场景。
2、先搞懂:Apifox MCP 到底能干啥
你可以把 Apifox MCP 理解成 AI 客户端通往 Apifox 的专属通道。
配置授权之后,AI 就能在权限范围内读取你的项目,也可以操作接口定义、数据模型、测试用例这些资源。(划重点:本文讲的是官方新版内测版本,别和旧版 MCP 搞混)〔1〕
- 老流程:AI 整理文档文本 → 人工复制到 Apifox 填表
- 新流程:AI 分析代码 → 通过 MCP 直接读写 Apifox 内的接口文档
接上 MCP,不等于接口写完了,文档就会自动跟着更新。 读代码、分析差异的是 AI 客户端,MCP 负责连接 Apifox。要处理哪些接口、什么时候同步,仍然需要你主动给 AI 下发指令,或者另行配置自动化流程。
接入本身不算复杂:在 Apifox 生成访问令牌,按照你用的工具(Codex、Claude Code、Trae 等)配置 MCP,连通后读取项目验证一下就行。这些内容官方文档里都写得很清楚,此处不再赘述。〔1〕
如果以前配置的是 npx apifox-mcp-server,注意核对新旧接入方式。〔2〕
⚠️ 注意:Token 不要提交到 Git 仓库;第一次尝试写入的时候,可以拿测试项目里的接口练手。
3、五个日常开发高频好用场景
3.1、接口写完,让 AI 补充接口文档
这是我觉得最香的用法。Controller、入参对象、出参对象、校验注解,代码里本身已经藏了大量接口信息,再手动搬到 Apifox 纯体力活。
不建议只丢一个 Controller 方法,就让 AI “生成完整接口文档”。很多字段校验规则、统一返回封装、异常返回逻辑,不一定写在这个接口方法里,很容易漏信息。
按我的使用体验,字段注释写清楚,再配上 @NotNull、@Size 这类校验注解,AI 通常就能整理出比较完整的字段定义。业务里的特殊限制,还是得单独交代。
比如我经常这样说:
阅读当前项目中的
POST /xxx/xxx接口代码,在 Apifox【项目 / 分支 / 模块 / 文件夹】中生成接口文档;已有同方法、同路径的接口则更新,无法确认的字段说明列出来。
后端可以少做很多重复录入,前端也能在团队统一的地方看到整理后的定义。
人工复核时,要特别留意字段约束。例如,Java 字段是 String,不代表它允许为空;请求示例里的值看着合理,也不代表符合业务规则。有必要的话,可以让 AI 标一句“待确认”,再做人工的确认即可。
3.2、接口迭代变更,一键整理联调变更说明
接口改完之后,前端最关心的从来不是一整篇完整文档,而是:这次到底改了啥?会不会影响我现有页面?
可以让 AI 对比代码和 Apifox 现有文档,输出变更差异:
对比当前项目中的
POST /xxx/xxx接口与现有 Apifox 接口文档,梳理字段、必填规则、响应数据等改动,标记出会影响前端现有调用的风险点,输出联调变更说明,本次只做对比,不修改文档。
这份差异清单,既可以用来自查有没有漏同步文档,也能直接当成前端变更通知初稿,不用自己逐行对比字段。
这里有个小坑:代码和文档不一致,不一定是本次迭代导致的,有可能是历史遗留不同步。
如果要输出本次迭代专属的变更日志,最好顺带把 Git 提交记录或者 diff 范围一起给 AI,避免把陈年旧账也算进来。
核对完变更清单,再让 AI 更新 Apifox。后端文档、前端变更通知,共用一套核对依据,不容易对不上。

3.3、批量检查模块接口,找出残缺文档
项目做久了,总会有一批 “能用但文档残缺” 的接口:参数没有说明、返回缺少示例、接口摘要写得含糊不清。
大家开发的时候心里清楚怎么调,就先放一边;等到交接、换人或者前端开发陌生模块,一堆坑集中爆发。
这类枯燥的检查工作交给 AI 最合适:
检查 Apifox【项目 / 分支】用户模块下全部接口,筛选出参数描述为空、缺少响应示例、接口摘要表意模糊的接口。按接口名称、请求方式、路径、问题点整理清单;分页数据请完整读取。本次仅检查,不修改任何文档。
拿到清单之后,我们再判断哪些文档优先补齐、哪些需要找当初开发的同学确认。
项目规模大的时候,建议按模块分批检查,一次性扫整个项目,清单太长不方便核对。
3.4、前端直接基于 Apifox 定义生成请求代码
这个工具不只是后端福利,前端同学也能用。接口定义已经维护在 Apifox,直接让 AI 读取接口,贴合项目现有规范生成请求函数和 TS 类型声明。

提示词建议写清楚项目规范,避免 AI 自创一套封装:
读取 Apifox【项目 / 分支】登录接口,结合当前前端项目已有的请求封装逻辑,生成请求函数、入参类型、响应类型。复用项目现有的鉴权、异常拦截、基础域名配置,不要新建请求工具;文档信息模糊的地方单独标注出来。
省去手动复制字段写类型的重复劳动,不用反复找后端要入参出参样例。
当然前提是:Apifox 文档本身和代码同步。如果文档早就落后代码,生成出来的类型自然也是错的,所以前面 “先对比、再更新” 的步骤很关键。
3.5、辅助梳理测试用例,覆盖正常和边界场景
接口写完自测,或者交给测试同学的时候,可以让 AI 基于接口定义梳理测试场景。
拿支付接口举例:除了正常支付成功,还要考虑金额边界、重复提交、订单异常状态等场景。但最终预期结果,必须依托业务规则,AI 不能自己凭空定逻辑。
参考提示词:
根据支付接口文档、业务代码逻辑,梳理正常流程、异常流程、边界场景的测试用例,包含前置条件、请求参数、预期结果、校验断言。业务上不确定预期结果的地方标注待确认。先输出用例清单,我确认之后,再写入 Apifox 测试用例模块;本次不发起接口请求。
后端可以拿来做自测,测试同学也能在这份基础上继续补充完善。
像支付、退款、消息推送这类敏感接口,一定要分清两个动作:保存用例 和 执行接口请求。先审好用例逻辑,再决定在哪套环境执行。
4、上手建议:先拿一个熟悉的接口试水
刚上手不用想着一步到位,让 AI 接管整个项目文档。挑一个你自己很熟悉的接口,先让 AI 读取 Apifox 文档、和代码做对比,看看它能不能准确识别差异。因为你清楚接口细节,很容易判断它有没有漏看、有没有脑补错误逻辑。
读取验证没问题之后,再尝试写入修改。修改前看变更清单,修改后回读核对,必填标记、业务校验规则、异常返回这几块是重灾区,重点检查。
写提示词尽量精准:项目、分支、模块、文件夹、请求方式 + 路径都带上,远比一句 “帮我改下订单接口” 更容易定位到目标接口,减少 AI 找错接口的情况。
很多人会问:它能不能替代 Swagger?我觉得没必要争这个。
Swagger 是从代码注解向外生成文档;Apifox MCP 是 AI 读懂代码之后,维护 Apifox 文档。两种路线。如果你们团队已经跑通稳定的 OpenAPI 导入同步方案,继续用就好;MCP 更适合用来做文档检查、差异对比、批量生成测试用例这类补充工作。
我对它的期待很务实:写完接口少复制几遍字段,迭代少漏同步改动,联调的时候少来回确认字段。但接口逻辑对不对、业务规则准不准确,最后把关的还是我们开发者自己。

