如何让 AI Agent 使用 Apifox CLI 创建接口文档

接口文档是一项人人都认为重要但没人想认领的任务。一个新接口发布了，参考文档却滞后了一周，而入门指南描述的还是你在两个迭代前就已经替换掉的 auth 流程。工作是实实在在的，但它重复性高且容易被延后。

这种（重要、重复、可延后）的特性组合正是 AI Agent 所擅长的。如果您的 Agent 能够运行终端命令，它就可以根据自然语言请求编写接口、撰写相关的指南文档并发布文档站。而 Apifox CLI 正是实现这一目标的关键：每个文档操作都是一个可脚本化的命令，并带有 Agent 可以读取并执行的结构化 JSON 输出。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

为什么选择 CLI，而不是 GUI 或 MCP 服务端

Agent 有三种方式可以处理您的接口文档，它们分别解决不同的问题。理清这些区别，决定了您是在费劲地应付工具，还是在高效地使用专为此任务而设计的工具。

方式	方向	驱动者	可评审的差异（diff）？
GUI	人类在浏览器中编辑	人工点击	否
MCP 服务端	读取您的规范 → 编写代码	运行在编辑器中的 Agent	在您的代码仓库中，而不是文档中
CLI	写入文档本身	运行在终端中的 Agent	是，每个命令都会被记录

当您希望 Agent 读取您的接口定义/规范并针对其生成客户端代码时，MCP 服务端是极佳的选择。Cursor 通过 MCP 读取文档的流程就是最典型的例子。但这与我们这里的需求恰好相反。我们希望 Agent 来产出文档：创建接口、撰写 Markdown 指南并发布网站。

为此，CLI 在三个方面更胜一筹。首先，它是确定性的：相同的命令会产生相同的结果。其次，它是可脚本化的：整个流程可以直接集成到 CI 中。最后，它在每次调用时都会返回 JSON，其中包含一个 agentHints.nextSteps 字段，用于告知 Agent 下一步可以做什么。最后一点比听起来更重要：这意味着 Agent 不需要摸索前进，而是遵循 CLI 本身的建议。

配置 Agent 的环境

安装 CLI 并进行一次身份验证。我们的安装指南涵盖了 Node 版本和 PATH；身份验证指南涵盖了 Token 和 CI 密钥。

npm install -g apifox-cli
apifox login --with-token <TOKEN>

从 Apifox 应用的“用户头像 → 账户设置 → API 访问令牌”中获取 Token。登录后它会保存在本地，因此 Agent 不需要每次调用都传递它。

每次写入操作都需要针对一个项目 ID 运行，您可以在“项目设置 → 基本设置”中找到该 ID，或者通过运行以下命令获取：

apifox project list

任何能够运行 shell 命令的编程 Agent 都可以在这里工作：Claude Code、Cursor、Codex 等。CLI 不在乎是谁在调用它；它只关心命令和 payload 是否正确。这就引出了让整个流程稳定可靠的唯一规则。

Agent 必须遵循的写入规范

用于创建资源的文档命令需要一个 JSON 文件。您的 Agent 绝不应该凭记忆手动构建该 JSON。模型凭空捏造字段名是运行失败的首要原因。CLI 为每次写入都提供了精确的数据模型，正确的执行顺序始终包含以下四个步骤：

1. Ask the CLI what the payload looks like
apifox cli-schema get doc-create
2. Generate the JSON file from that schema
3. Validate before you write (catches a missing field locally)
apifox cli-schema validate doc-create --file ./doc.json
4. Only now run the real command
apifox 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 <key> first and build from that schema.
Validate every file with apifox cli-schema validate <key> --file <path> before any create or update.
Always pass --projecton write commands.
Read the agentHints.nextSteps field in each JSON response to choose the next command.
If a write comes back blocked by permissions, stop and ask the human; do not pick a workaround.

这五行规则决定了 Agent 是能够稳定交付文档，还是只能靠猜测 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.json
apifox schema create --project <projectId> --file ./refund-schema.json

现在是接口部分。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/<refundSchemaId>" }
  }
}

apifox cli-schema validate endpoint-create --file ./refunds-endpoint.json
apifox endpoint create --project <projectId> --file ./refunds-endpoint.json

/refunds 的参考文档现在已经存在，它是根据你团队编辑的同一个定义渲染出来的。对于参考文档，没有单独的“导出文档”步骤；在接口落地的瞬间，它就已经在项目中实时生效了。这就是“数据模型优先”源头带来的回报：参考文档不会产生偏差，因为它就是数据模型。

步骤 2：编写指南，而不仅仅是参考文档

从数据模型生成的参考文档只是优秀文档的一半。另一半是说明性文字：入门页面、认证流程、迁移说明。在 Apifox 中，这些以 Markdown 文档的形式存在于项目的文档树中，由 doc 命令组进行管理。

doc-create 数据模型只需要一个 name；content 用于存放 Markdown 内容，folderId 则用于将其放入树中（0 代表根目录）。因此，Agent 起草的快速入门文件变成了 quickstart.json：

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}

apifox doc list --project <projectId>
apifox cli-schema validate doc-create --file ./quickstart.json
apifox doc create --project <projectId> --file ./quickstart.json

这正是 Agent 发挥价值的地方。只需让它“编写一份引导新开发者从获取 API key 到完成首次退款的快速入门指南”，它就会起草 Markdown，将其包装进数据模型所需的 payload 中，进行校验并创建文档。无需浏览器，无需复制粘贴。由于内容只是一个字符串字段，Agent 可以根据任务需求编写任意长度或深度的详细指南。

步骤 3：发布文档站

准备好参考文档和指南后，Agent 也可以直接在终端进行发布。有两个命令组处理此操作，但其中有一个命名上的区别经常让人混淆：

doc：项目 API 树内部的 Markdown 文档（你在步骤 2 中创建的内容）。
docs-site：托管的、公开的文档站。
shared-doc：提供给合作伙伴的分享链接，而不是一个完整的网站。

apifox docs-site list --project <projectId>
apifox cli-schema get docs-site-create
apifox docs-site create --project <projectId> --file ./docs-site.json

当您希望直接通过终端定义一个公开站点时，可以使用 docs-site；而当您只需要一个可以发送给他人的链接时，可以使用 shared-doc。由于两者都是命令，发布便成了一个脚本化的步骤，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 等参数，以此来缩小输出范围。通过这种方式，单个项目可以为每个服务单独输出一个文档文件。

一个完整的端到端示例

以下是作为一个自然语言请求的完整闭环，以及 Agent 为满足该请求而运行的命令。

你： “我们刚刚添加了一个包含 POST /refunds 和 GET /refunds/{id} 的支付服务。请为这两个接口编写文档，写一篇解释幂等密钥（idempotency keys）的简短指南，并将其发布到我们的文档站。”

Agent 遵循其规则，运行以下命令：

Create the shared data model
apifox cli-schema validate schema-create --file ./refund-schema.json apifox schema create --project $PID --file ./refund-schema.json
Create both endpoints
apifox endpoint create --project $PID --file ./post-refunds.json apifox endpoint create --project $PID --file ./get-refund.json
Author the idempotency guide as a Markdown doc
apifox doc create --project $PID --file ./idempotency-guide.json
Publish
apifox docs-site create --project $PID --file ./docs-site.json

您只需审查生成的 diff 差异，支付服务的文档便已准备就绪并上线。以前需要花一下午时间在不同工具间频繁切换，现在只需一个请求和一次审查即可完成。

将其接入 Agent 循环或 CI

因为每一个步骤都是一个命令，所以整个流程可以轻松融入 CI 或 Agent 的任务循环中。以下是一个在每次 push 时重新生成并提交 Markdown 参考文档的最小步骤：

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md

若要更全面地了解如何针对 CLI 端到端地运行 Agent，请参阅《从 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 流程，以确保其基于真实的数据模型运行，而不是凭空猜测。

缺失项目 ID。 每次调用 doc、docs-site 和 export 时都需要携带 --project <projectId>（即设置中的 ID，而不是易读的项目名称）。大多数“报错”反馈都是因为这个问题。

混淆了 doc、docs-site 和 shared-doc。 它们是三种不同的东西：目录树中的 Markdown 页面、托管的文档站以及分享链接。在 Agent 开始写入文档之前，让它先确认任务指的是哪一个。

在 CI 中未设置 Token。 apifox login 会将 Token 存储在运行它的机器上。全新的 CI 运行器（runner）中没有该 Token，因此在执行任何命令之前，请在同一个任务（job）中运行 login --with-token，并将 Token 保存在机密变量（secret）中。

指向空地址的 $ref。 当接口使用 #/definitions/{schemaId} 引用某个数据模型时，该数据模型必须首先存在。请在创建使用它们的接口之前，先创建好对应的数据模型。

FAQ

哪些 AI Agent 可以运行 Apifox CLI？ 任何可以运行 shell 命令的 Agent 都可以：Claude Code、Cursor、Codex 以及类似的编程 Agent。CLI 与具体的 Agent 无关，它只需要正确的命令和有效的 Payload（有效载荷）。

我需要付费方案吗？ 不需要。虽然 Apifox 不是开源的，但免费版加上 apifox-cli 就足以覆盖本文介绍的“创建并发布”流程。

Agent 会不小心覆盖现有的文档吗？ create 会添加新的资源。修改现有资源需要使用 update，它的行为方式不同，并且需要自己的安全防范措施；这在《更新您的接口定义/规范》配套指南中有所提及。

这与普通的 AI 文档生成器有什么不同？ 通用的 AI 文档工具是从您的代码中生成文本。而这种方式则是在您的 API 平台内部生成结构化的文档（包括接口、数据模型、指南和已发布的文档站），数据源保持同步，绝不会与团队实际编辑的内容产生偏差。

总结

能够运行 Apifox CLI 的 Agent 可以完全接管人们常常推迟的文档编写工作：它能创建接口、围绕接口撰写指南并发布文档站。这一切只需通过自然语言请求即可完成，并且每次写入都受到数据模型校验的保护。您的角色也从“写文档”转变为“审查 diff（代码差异）”。

让这一流程切实可靠的核心准则在于“写入仪式”：获取数据模型、进行校验，然后创建。只要将这个循环、上文的五行规则块以及项目 ID 提供给您的 Agent，文档就再也不会是滞后于代码的繁琐负担。下载 Apifox 以获取 CLI，或阅读 Apifox CLI 完整指南以获取完整的命令参考。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

立即体验 Apifox

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋企业微信

@Apifox 专属顾问