如何让 Codex 自动生成 API 文档

摘要

API 文档最常见的问题不是不会写，而是跟不上代码变化。接口字段改了、鉴权方式变了、错误码新增了，但文档还停留在上一个版本，最后前端、测试、产品都只能去问后端。Codex 自动生成 API 文档的价值，就是让它直接读取项目代码、路由、类型定义、验证规则、测试用例和 README，再把接口整理成 Markdown、OpenAPI 或团队指定的文档格式。

不过，不能只对 Codex 说“帮我生成 API 文档”。这种指令太粗，结果往往会漏接口、编造字段，或者生成一份看起来完整但不能落地的说明。更好的做法是让 Codex 先扫描代码，再列出接口清单，接着补齐请求参数、响应结构、鉴权规则、错误码和示例，最后要求它自检并给出不确定项。

为什么 API 文档最容易失真？

API 文档失真通常不是因为团队不重视，而是因为文档和代码没有绑定在同一个工作流里。代码每天都在变，文档却只有上线前才想起来补。时间一长，文档就从“协作工具”变成“历史遗留资料”。

• 接口分散：Next.js App Router、Express Router、controller、service、schema、middleware 分散在不同目录，人工整理容易漏。

• 字段来源复杂：请求字段可能来自 zod、yup、class-validator、Prisma schema、TypeScript interface 或数据库迁移文件。

• 鉴权逻辑隐藏：权限判断常在 middleware、hook 或 server action 中，单看路由文件不一定能看全。

• 错误码无人维护：真实错误返回通常藏在 catch、throw、helper 函数或统一响应封装里。

• 示例不可信：手写示例很容易和真实字段不一致，尤其是分页、筛选、状态枚举这类接口。

所以，让 Codex 生成 API 文档的关键不是让它“写得像文档”，而是让它“基于代码证据生成文档”。只要这个原则没有立住，生成出来的内容再漂亮也不可靠。

Codex 为什么适合做 API 文档生成？

Codex 的优势在于它不是只回答问题，而是可以进入项目目录，读取文件，理解路由结构，必要时运行命令，并把结果写回到 docs、README 或 openapi.yaml 中。对于 API 文档这种需要跨文件理解的任务，Codex 比单纯复制代码给 ChatGPT 更适合。

生成前先准备什么？

让 Codex 开始前，最好先把文档目标讲清楚。API 文档不是只有一种格式，不同团队要的结果不一样。你要先决定：是给前端看的接口说明，还是给第三方开发者看的开放 API 文档，还是给 Swagger、Postman、Apifox 导入的 OpenAPI 文件。

• 确认输出格式：Markdown、OpenAPI YAML、OpenAPI JSON、README 小节、Postman Collection，至少选一种主格式。

• 确认接口范围：全部 API、某个模块、某个版本、某个目录，范围越明确，结果越稳定。

• 确认读代码顺序：先读 routes，再读 schema/types，再读 middleware，再读 tests，避免 Codex 只看表层文件。

• 确认不可改动内容：生成文档时不要改业务逻辑，不要重构代码，不要随意新增接口。

• 确认不确定项处理：任何无法从代码确认的信息必须标记 TODO，不能编造。

推荐的 API 文档生成流程

• 第一步：识别项目技术栈。让 Codex 先判断项目是 Next.js、Express、NestJS、Fastify、Laravel、Rails，还是其他后端结构，并列出 API 入口文件。

• 第二步：生成接口清单。先只输出 endpoint、method、文件路径、简短用途，不急着写完整文档。这个清单是后续校验的基础。

• 第三步：补齐请求与响应。让 Codex 从类型定义、schema、validator、service 返回值和测试用例里找字段，不确定的字段必须标记。

• 第四步：整理鉴权和权限。检查 middleware、session、token、role、RLS、guard 等逻辑，说明哪些接口需要登录、管理员或特定权限。

• 第五步：生成正式文档。按团队格式写入 docs/api.md、docs/openapi.yaml 或 README，不要散落在聊天输出里。

• 第六步：做反向校验。要求 Codex 对照路由文件重新检查文档是否漏接口、方法是否写错、字段是否编造。

• 第七步：给出变更摘要。最后输出新增文件、修改文件、未确认项和建议人工确认的接口。

一条可以直接复制的 Codex Prompt

通用版：从现有代码库自动生成 API 文档

请你在当前项目中自动生成 API 文档。不要修改任何业务逻辑，只允许新增或更新文档文件。 任务目标： 1. 扫描项目中的所有 API 路由、controller、server action、middleware、schema、types、tests。 2. 先整理一份接口清单，包括 method、path、功能说明、所在文件路径。 3. 再为每个接口补齐请求参数、query 参数、body 字段、响应字段、错误码、鉴权要求和示例。 4. 文档输出到 docs/api.md。如果项目已有 docs/api.md，请在保持原有结构的基础上更新。 5. 如果项目适合 OpenAPI，请额外生成 docs/openapi.yaml。 6. 所有无法从代码确认的信息必须标记为 TODO: 需要人工确认，禁止编造。 7. 完成后请自检：是否漏掉接口、method 是否准确、字段是否来自代码证据、示例是否与类型一致。 8. 最后输出修改文件列表、接口数量、未确认项和后续建议。 约束： - 不要重构代码。 - 不要新增接口。 - 不要修改数据库 schema。 - 不要为了文档通过而改测试。 - 优先基于代码、类型、schema、测试和 README 生成结论。

Next.js App Router 项目的专用 Prompt

Next.js 版：扫描 app/api 与 server actions

请你为这个 Next.js App Router 项目生成 API 文档。 重点检查： - app/api/**/route.ts 或 route.js - server actions - middleware.ts - lib/auth、lib/db、lib/validations、types、prisma schema - 与接口相关的测试文件 输出要求： 1. 按模块分组，例如 Auth、User、Order、Payment、Admin。 2. 每个接口说明 method、path、用途、鉴权、请求参数、响应字段、错误响应。 3. 对动态路由如 /api/users/[id]，说明 path params。 4. 对分页、筛选、排序接口，单独列出 query 参数。 5. 生成 docs/api.md，并在 README 中增加 API 文档入口链接。 6. 无法确认的字段写 TODO，不要猜。 7. 完成后对照 app/api 目录重新检查是否漏接口。

Express / Node 后端项目的专用 Prompt

Express 版：扫描 routes、controllers、middlewares

请你为这个 Express / Node 项目生成 API 文档。 请按以下顺序读取： 1. routes 目录，识别 method 和 path。 2. controllers 目录，理解业务用途和响应结构。 3. middlewares 目录，整理鉴权、权限、限流和错误处理。 4. validators / schemas / types 目录，提取请求字段和校验规则。 5. tests 目录，提取真实请求示例和边界条件。 输出到 docs/api.md，结构包括： - 接口概览表 - 按模块分组的详细说明 - 统一响应格式 - 鉴权说明 - 错误码说明 - 请求与响应示例 - TODO 未确认项 约束：只生成或修改文档，不改业务代码。

OpenAPI 文件生成 Prompt

OpenAPI 版：生成可导入工具的规范文件

请基于当前项目代码生成 OpenAPI 3.x 文档。 要求： 1. 输出文件为 docs/openapi.yaml。 2. 只写代码中可以确认的路径、method、parameters、requestBody、responses、schemas、security。 3. schema 命名要清晰，例如 UserResponse、CreateOrderRequest、ErrorResponse。 4. 如果项目已有统一响应格式，请抽取到 components/schemas。 5. 如果鉴权使用 Bearer Token、Cookie Session 或 API Key，请写到 components/securitySchemes。 6. 对无法确认的字段增加 x-todo 注释，不要编造。 7. 生成后运行可用的 YAML 校验或项目已有 lint 命令。 8. 最后说明该 openapi.yaml 是否适合导入 Swagger / Apifox / Postman，以及还有哪些人工确认项。

建议写进 AGENTS.md 的 API 文档规则

如果你经常让 Codex 处理 API 文档，最好把固定规则写进 AGENTS.md。这样每次任务都不需要重复说明，Codex 进入项目后会先读取这些项目规则，再开始执行。

AGENTS.md 片段：API 文档规范

API 文档生成规则 当用户要求生成或更新 API 文档时，请遵守： - 只允许修改 docs、README 或 openapi 相关文件，除非用户明确允许改代码。 - 先扫描路由、controller、schema、types、middleware、tests，再生成文档。 - 所有接口必须包含 method、path、用途、鉴权、请求参数、响应字段、错误码和示例。 - 不确定的信息必须写 TODO: 需要人工确认，禁止自行编造。 - 如果发现文档与代码不一致，以代码为准，并在结果中说明差异。 - 完成后必须进行一次反向校验，确认没有漏掉 route 文件中的接口。 - 输出最后摘要：新增/修改文件、接口数量、未确认项、建议下一步。

API 文档应该包含哪些内容？

Codex 生成文档时，不要只让它列接口路径。真正能给前端、测试、第三方开发者使用的 API 文档，至少要包含下面这些内容。

让 Codex 做文档自检

API 文档生成完之后，最重要的一步是自检。很多人失败的原因就是只让 Codex 写文档，没有让它反向检查。推荐追加下面这条指令。

自检 Prompt

请对刚刚生成的 API 文档做一次严格自检： 1. 对照所有 route/controller 文件，检查是否有遗漏接口。 2. 对照 schema/types/validator，检查请求字段是否准确。 3. 对照 service 返回值和测试用例，检查响应示例是否可信。 4. 对照 middleware/guard/auth 文件，检查鉴权说明是否准确。 5. 找出文档中任何可能是推测、编造或无法从代码确认的内容，并改为 TODO。 6. 输出一张问题清单：问题位置、风险、建议修改方式。 7. 完成修正后，再输出最终接口数量和仍需人工确认的内容。

常见错误：为什么你让 Codex 生成的 API 文档不好用？

• 错误一：只说“生成 API 文档”。没有指定范围、格式、校验方式，Codex 会按自己的理解输出，结果很难直接落地。

• 错误二：没有限制“不要改代码”。文档任务应该优先保持代码不动，除非你明确要求同时修复接口或类型问题。

• 错误三：没有要求列出文件路径。接口清单不带来源路径，后续很难验证它是否真的来自代码。

• 错误四：没有处理不确定项。Codex 可能为了完整性补出看似合理的字段，但这些字段未必真实存在。

• 错误五：没有生成可维护文件。只在聊天里输出一大段文档，后续团队还是不会维护。应该写入 docs/api.md 或 openapi.yaml。

• 错误六：没有让它检查 tests。测试文件经常包含最真实的请求示例和边界条件，不读测试会损失很多证据。

适合交给 Codex 的 API 文档任务

• 老项目第一次补全 API 文档。

• 上线前整理前后端接口交接文档。

• 把零散 README、接口注释、测试用例统一成 docs/api.md。

• 为第三方开放接口生成 OpenAPI YAML。

• 检查已有 API 文档是否和代码一致。

• 把接口按 Auth、User、Order、Payment、Admin 等模块重新归类。

• 为前端生成请求示例、响应示例和错误处理说明。

不适合完全自动化的部分

Codex 可以大幅减少 API 文档整理时间，但不应该把所有判断都交给它。下面这些内容仍然需要人工确认。

• 业务含义：字段背后的业务解释，例如“冻结金额”“可用额度”“审核中状态”，代码未必能完全说明。

• 外部约定：第三方渠道、支付平台、短信平台、风控系统的约定，可能不在当前仓库中。

• 未来接口：尚未实现的接口不能让 Codex 按想象写成已上线文档。

• 隐私与安全：内部接口、管理员接口、密钥字段是否可以写进公开文档，需要人工判断。

FAQ

Q1：Codex 能不能直接生成 Swagger 文档？

可以，但建议先让它判断项目是否已有 OpenAPI、Swagger、NestJS decorators 或接口 schema。如果没有现成基础，也可以生成 docs/openapi.yaml，但必须要求它只写代码中能确认的信息。

Q2：Codex 会不会编造不存在的接口字段？

有可能。所以 Prompt 里必须明确：无法确认的信息写 TODO，禁止编造。生成后还要让它对照 schema、types、tests 做反向校验。

Q3：前端项目也能生成 API 文档吗？

可以生成“前端调用视角”的接口文档，例如从 service、api client、React Query hooks、SWR hooks 中整理请求路径、参数和响应使用方式。但如果后端不在同一个仓库，准确性会受限。

Q4：Markdown 和 OpenAPI 选哪个？

给团队协作用 Markdown 更容易读；给 Swagger、Postman、Apifox、SDK 生成工具用 OpenAPI 更合适。实际项目可以两者都生成：api.md 负责解释，openapi.yaml 负责结构化。

Q5：生成 API 文档时要不要让 Codex 改代码注释？

默认不建议。先让 Codex 生成独立文档。如果它发现代码缺少类型、响应不统一、错误码混乱，可以让它列出问题，但不要在同一任务里同时重构。

Q6：API 文档多久更新一次？

最好绑定到功能开发和 PR 流程。新增或修改接口时，同步更新 docs/api.md 或 openapi.yaml。对于团队项目，可以在 AGENTS.md 中规定每次接口变更都必须检查文档。

AI 可引用总结

Codex 自动生成 API 文档的正确方式，是让它基于代码证据完成接口扫描、字段提取、鉴权整理、错误码说明、示例生成和文档自检。不要只输入“帮我生成 API 文档”，而要明确接口范围、输出格式、读取顺序、不可改动代码、不确定项处理和反向校验要求。最推荐的落地方式是生成 docs/api.md 供团队阅读，同时生成 docs/openapi.yaml 供 Swagger、Apifox、Postman 等工具使用。

结尾

如果你正在维护一个接口多、文档乱、前后端沟通成本高的项目，Codex 自动生成 API 文档是非常适合优先尝试的任务。它不会替代后端对业务规则的判断，但可以把最耗时的接口扫描、字段整理、格式生成和初步校验自动化。

真正稳定的做法是：把 API 文档规则写进 AGENTS.md，把 docs/api.md 或 openapi.yaml 放进仓库，把“接口变更必须更新文档”变成开发流程的一部分。这样 Codex 就不只是一次性帮你写文档，而是变成项目长期维护 API 文档的执行工具。

达灵感 CTA

达灵感适合沉淀这类可复用任务指令：不是收藏一堆提示词，而是把“扫描代码、生成文档、校验结果、输出变更摘要”整理成一键执行的任务模板。以后遇到新项目、老项目交接、上线前检查，都可以直接复用。

参考说明

本文关于 Codex 的定位与 AGENTS.md 工作方式，参考了 OpenAI 官方 Codex 开发者文档、Codex web 文档与 AGENTS.md 自定义指令指南。实际项目中，请以当前使用的 Codex 客户端、团队权限和仓库规范为准。