接口文档始终是团队里公认重要、却又常常没人主动承担的工作。一个新接口刚刚上线，API 文档可能还要滞后一周；而快速入门指南里写的，仍然是你在两个迭代前就已经替换掉的 auth 认证流程。这项工作真实存在、不可或缺，但也因为重复性高、优先级常被挤压而容易一再延后。
而这种“重要、重复、可延后”的工作类型，恰恰非常适合交给 AI Agent 处理。如果您的 Agent 能运行终端命令，它就可以根据自然语言指令创建接口、生成 API 说明文档、编写使用指南，并进一步发布文档站点。Apifox CLI 正是实现这套自动化流程的关键工具：几乎每个文档操作都可以通过脚本命令完成，并返回 Agent 可读取、可执行的结构化 JSON 输出。
为什么选择 CLI，而不是 GUI 或 MCP 服务端
AI Agent 处理 API 文档通常有三种方式，每种方式解决的问题并不相同。搞清楚它们之间的差异，决定了您是在勉强适配工具，还是在使用真正适合自动化文档生成的方案。
| 方式 | 方向 | 驱动者 | 可评审的差异（diff）？ |
|---|---|---|---|
| GUI | 人类在浏览器中编辑 | 人工点击 | 否 |
| MCP 服务端 | 读取您的规范 → 编写代码 | 运行在编辑器中的 Agent | 在您的代码仓库中，而不是文档中 |
| CLI | 写入文档本身 | 运行在终端中的 Agent | 是，每个命令都会被记录 |
如果您的目标是让 Agent 读取现有 API 定义或接口规范，并在此基础上生成客户端代码，那么 MCP 服务端确实是很合适的选择。比如 Cursor 通过 MCP 读取文档并辅助开发，就是一个非常典型的应用场景。不过，本文要解决的问题刚好相反。这里真正需要的，不是让 Agent 去消费 API 文档，而是让它来生成和维护文档：包括创建接口、撰写 Markdown 指南，以及将文档网站发布出去。
在这个场景下，CLI 有三点明显优势。第一，它具备确定性：同样的命令会得到同样的结果。第二，它天然适合脚本化：整套流程都可以无缝接入 CI/CD。第三，也是最关键的一点，每次调用都会返回 JSON，其中包含 agentHints.nextSteps 字段，用于提示 Agent 下一步应该执行什么操作。这一点比看上去更有价值：Agent 不需要盲猜流程，而是可以按照 CLI 返回的建议继续推进任务。
配置 Agent 的环境
首先安装 Apifox CLI，并完成一次身份验证。安装指南会说明 Node 版本和 PATH 环境变量要求；身份验证指南则涵盖 Token 与 CI 密钥的配置方式。
npm install -g apifox-cliapifox login --with-token
您可以在 Apifox 应用的“用户头像 → 账户设置 → API 访问令牌”中获取 Token。登录成功后，Token 会保存在本地环境中，因此 Agent 后续执行命令时无需每次重复传入。
Agent 必须遵循的写入规范
用于创建资源的文档命令通常需要一个 JSON 文件。您的 Agent 绝不应该依靠记忆手动拼写这个 JSON。模型凭空臆造字段名，是导致命令执行失败最常见的原因。Apifox CLI 为每一次写入都提供了精确的数据模型，因此正确的执行顺序应始终遵循以下四个步骤：
1. Ask the CLI what the payload looks likeapifox cli-schema get doc-create2. Generate the JSON file from that schema3. Validate before you write (catches a missing field locally)apifox cli-schema validate doc-create --file ./doc.json4. Only now run the real commandapifox doc create --project--file ./doc.json
建议将这一循环直接写入 Agent 的执行规则中。这样做的意义在于，它能把“模型胡乱生成了一个不存在的字段”转变为“本地校验器直接拦截了这个字段”，而这正是稳定运行与构建失败之间的关键差别。下面这段规则块，可以直接复制到 Agent 的 system prompt，或写入 CLAUDE.md / .cursorrules 中：
Apifox CLI rules:Never hand-write a JSON payload. Run apifox cli-schema get
这五条规则，基本决定了 Agent 是能稳定生成 API 文档并顺利交付，还是只能靠猜 payload 不断碰壁。
步骤 1：基于接口和数据模型创建参考文档
在 Apifox 中，API 参考文档是根据项目中的接口定义和数据模型自动生成的。因此，Agent 的第一项任务，就是先把这些基础内容创建出来。假设您给它的任务是：
“添加一个 POST /refunds 接口，该接口接收订单 ID 和金额，并记录其成功和校验错误响应。”通常情况下，Agent 会先创建可复用的数据模型，再创建引用该模型的接口。执行 apifox cli-schema get schema-create 后可以看到，数据模型需要一个 name 和一个标准的 jsonSchema object。因此，Agent 会生成类似下面的 refund-schema.json 文件：
{"name": "Refund","description": "A refund issued against an order","jsonSchema": {"type": "object","required": ["orderId", "amount"],"properties": {"orderId": { "type": "string" },"amount": { "type": "number" },"reason": { "type": "string" }}}}
随后先校验，再执行创建：
apifox cli-schema validate schema-create --file ./refund-schema.jsonapifox schema create --project
接下来进入接口创建阶段。endpoint-create 数据模型要求提供 method 和 path，并允许通过 #/definitions/{schemaId} 形式的 $ref 引用刚刚创建的数据模型。于是 Agent 会写出 refunds-endpoint.json：
{"name": "Create refund","method": "post","path": "/refunds","status": "developing","requestBody": {"type": "application/json","jsonSchema": { "$ref": "#/definitions/
apifox cli-schema validate endpoint-create --file ./refunds-endpoint.jsonapifox endpoint create --project
当命令执行完成后，/refunds 的 API 参考文档就已经存在了，而且它是直接基于团队当前维护的同一份定义实时渲染出来的。对于参考文档来说，不需要额外再执行一次“导出文档”步骤；接口一旦创建完成，文档也就同步生效。这正是“数据模型优先”策略带来的优势：API 文档不会偏离真实定义，因为它本身就是由数据模型生成的。
步骤 2：编写指南，而不仅仅是参考文档
由数据模型自动生成的 API 参考文档，只构成优秀文档体系的一半。另一半则是说明性内容，例如快速入门、认证说明、迁移指南等。在 Apifox 中，这类内容以 Markdown 文档的形式存在于项目文档树中，并由 doc 命令组进行管理。
doc-create 数据模型只要求一个 name；其中 content 用于承载 Markdown 正文，folderId 用于指定它所在的目录节点（0 表示根目录）。因此，Agent 起草的快速入门文档会被组织成类似下面的 quickstart.json：
{"name": "Quickstart: Your first refund","content": "# QuickstartnnThis guide takes you from API key to your first refund in five minutes...","folderId": 0}
apifox doc list --project
这里正是 AI Agent 发挥效率价值的地方。您只需要告诉它“请写一份帮助新开发者从获取 API key 到完成首次退款的快速上手指南”，它就可以自动起草 Markdown 内容，将其封装成符合数据模型要求的 payload，完成校验并创建文档。整个过程不需要打开浏览器，也不需要手动复制粘贴。由于内容本质上只是一个字符串字段，Agent 还可以根据需要输出更长、更细致的 API 使用指南或开发文档。
步骤 3：发布文档站
当参考文档和说明性指南都准备好之后，Agent 同样可以直接在终端中完成文档站发布。这里涉及两个相关命令组，不过它们的命名差异经常让人混淆：
doc：项目 API 树内部的 Markdown 文档（即步骤 2 中创建的内容）。docs-site：托管并对外展示的完整文档站点。shared-doc：用于分享给合作伙伴的文档链接，而不是一个完整的网站。
apifox docs-site list --project
如果您希望直接通过终端创建一个公开可访问的 API 文档网站，应使用 docs-site；如果只是想生成一个可以发给外部协作者的文档链接，则应使用 shared-doc。由于这两个动作本质上都是 CLI 命令，所以发布本身也能变成一个脚本化步骤。Agent 完全可以在每次文档修改后自动执行发布，一旦命令返回，托管站点就会即时反映最新内容。
步骤 4（可选）：导出便携式副本
有些时候，您可能还需要把文档导出为文件，例如导出成可单独托管的 HTML 页面、适用于静态站点生成器的 Markdown 文件，或交付给下游系统使用的 OpenAPI 定义。export 命令可以同时满足这三类需求：
apifox export --project--format html --output ./api-docs.html apifox export --project--format markdown --output ./api-docs.md apifox export --project--format openapi --oas-version 3.1 --output ./openapi.json
如果您的项目包含多个服务，而您只希望为其中某个服务导出文档，可以通过 apifox export --help 查看 --scope、--api-ids 和 --folder-ids 等参数，从而精确缩小导出范围。借助这种方式，单个项目也可以分别产出多个服务独立的 API 文档文件。
一个完整的端到端示例
下面是一个完整的自然语言请求闭环，以及 Agent 为完成该请求而执行的典型命令。
你： “我们刚刚添加了一个包含POST /refunds和GET /refunds/{id}的支付服务。请为这两个接口编写文档，写一篇解释幂等密钥（idempotency keys）的简短指南，并将其发布到我们的文档站。”
Agent 会按照既定规则，依次运行如下命令：
Create the shared data modelapifox cli-schema validate schema-create --file ./refund-schema.json apifox schema create --project $PID --file ./refund-schema.jsonCreate both endpointsapifox endpoint create --project $PID --file ./post-refunds.json apifox endpoint create --project $PID --file ./get-refund.jsonAuthor the idempotency guide as a Markdown docapifox doc create --project $PID --file ./idempotency-guide.jsonPublishapifox docs-site create --project $PID --file ./docs-site.json
您要做的，只是审查生成出来的 diff 差异，然后支付服务的 API 文档就已经准备完成并成功上线。过去可能需要花费半天时间在多个工具之间切换、整理、复制和发布，而现在只需要一次自然语言请求和一次审查流程即可完成。
将其接入 Agent 循环或 CI
由于每一步都可以通过命令执行，因此整套 API 文档自动化流程非常容易接入 CI，或者并入 Agent 的任务循环。下面是一个最小化示例：在每次 push 后重新生成并提交 Markdown 参考文档。
- name: Regenerate API docsrun: |npm install -g apidog-cliapidog login --with-token ${{ secrets.APIDOG_TOKEN }}apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
如果您希望更系统地理解，如何在 CLI 场景中让 AI Agent 端到端跑通整个 API 文档工作流，可以继续阅读《从 PRD 到测试循环》（From PRD to Testing Loop）以及《如何配置 5 个 AI Agent 以构建完整的 API》（How to Set Up 5 AI Agents to Build a Complete API）。这两篇文章的底层模式与本文是一致的：先清晰表达意图，再让 Agent 将其转化为可验证的 CLI 调用，最后由人类回头审查输出结果。
关于权限的一点说明
通过 Agent 写入项目内容时，可能会受到权限限制。如果 create 命令返回“被拦截”之类的提示，通常说明该项目或该分支关闭了“外部 AI 编辑权限”。这时您有两个可行选项：其一是在“项目设置” → “功能设置” → “AI 功能设置”（Apifox 客户端 2.8.32+）中开启直接编辑权限；其二是让 Agent 在隔离的 AI 分支中完成文档修改，并以合并请求（merge request）的方式提交。关于更新接口定义或规范的配套指南里，已经完整介绍了 AI 分支工作流；当 Agent 在受保护分支上创建文档时，这套流程同样适用。
常见问题与坑
Agent 手动构建了 JSON。 这是最常见的失败原因。请在 Agent 指令中强制执行 cli-schema get → cli-schema validate → create 这一流程，确保它始终基于真实的数据模型工作，而不是依赖猜测生成 payload。
缺失项目 ID。 每次调用 doc、docs-site 和 export 时，都必须携带 --project （也就是设置中的项目 ID，而不是可读的项目名称）。大量“命令报错”实际上都源于这里。
混淆了 doc、docs-site 和 shared-doc。 这三者分别对应文档目录树中的 Markdown 页面、托管的 API 文档站，以及分享用的文档链接。在 Agent 开始写入前，最好先让它确认任务目标到底是哪一种。
在 CI 中未设置 Token。 apifox login 会把 Token 存储在执行该命令的机器上。全新的 CI runner 默认不会保留这个 Token，因此在执行任何 CLI 命令前，请在同一个 job 中先运行 login --with-token，并将 Token 安全地保存在 secret 变量中。
指向空地址的 $ref。 当接口通过 #/definitions/{schemaId} 引用某个数据模型时，对应的数据模型必须已经存在。也就是说，请务必先创建 schema，再创建依赖它的接口定义。
FAQ
哪些 AI Agent 可以运行 Apifox CLI？ 任何支持执行 shell 命令的 Agent 都可以，例如 Claude Code、Cursor、Codex 以及类似的编程型 AI Agent。CLI 与具体使用哪一个 Agent 无关，它只依赖正确的命令和有效的 Payload（有效载荷）。
我需要付费方案吗？ 不需要。虽然 Apifox 本身不是开源产品，但免费版配合 apifox-cli 已经足以覆盖本文介绍的 API 文档创建、维护与发布流程。
Agent 会不小心覆盖现有的文档吗？ create 只会新增资源。若要修改已有资源，则需要使用 update，其行为逻辑不同，也需要额外的安全防护措施；这些内容在《更新您的接口定义/规范》配套指南中已有提及。
这与普通的 AI 文档生成器有什么不同？ 通用型 AI 文档工具通常是从代码仓库中生成说明文字；而这里的方式，是直接在 API 平台内部生成结构化文档，包括接口、数据模型、说明指南以及已发布的文档站。由于数据源始终保持一致，因此不会出现文档内容与团队真实维护结果脱节的问题。
总结
一个能够运行 Apifox CLI 的 AI Agent，几乎可以完整接管那些常常被团队拖延的 API 文档工作：它不仅能创建接口定义，还能围绕接口编写使用指南，并进一步发布文档站点。这一切都可以通过自然语言驱动完成，而且每一次写入都受到数据模型校验保护。您的角色，也从“亲自写文档”转变为“审查 diff（代码差异）”。
要让这套 API 文档自动化流程真正稳定可靠，核心原则就在于固定的“写入仪式”：先获取数据模型，再进行校验，最后执行创建。只要把这个循环、前文提到的五行规则块，以及正确的项目 ID 一并提供给您的 Agent，接口文档就不再会是滞后于代码的沉重负担。下载 Apifox 获取 CLI，或继续阅读 Apifox CLI 完整指南，即可查看更全面的命令参考。
开发必备：API 全流程管理神器 Apifox
在介绍完上面的自动化文档方案后，我还想额外推荐一个对开发者同样非常重要的效率工具——Apifox。作为集 API 文档、调试、设计、测试、Mock、自动化测试于一体的平台，Apifox 已成为许多团队进行 API 全生命周期管理和提升研发效率的首选工具。
如果你正在做接口开发，不妨体验一下它友好的界面设计与完整的功能体系。Apifox 完全兼容 Postman 和 Swagger 数据格式，数据导入非常便捷，即使是新手开发者也能快速上手，点击这里即可注册使用。
值得一提的是，除了适用于个人开发者和常规团队协作之外，对于有高安全合规要求、或需要在内网环境中协同工作的企业用户，Apifox 还提供了可深度定制的私有化部署方案。
