结论先说
- 别让 Codex 一口气扫描几十个控制器直接吐出几千行 YAML,必须拆成「路由盘点 → 分组生成 → 自动 Lint 校验」三段式。先输出精简路由清单确认没有漏掉前缀、全局鉴权中间件和统一响应包装器,再按业务模块生成
openapi.yaml,准确度能大幅提高。 - 明确锁定 OpenAPI
3.1.0语法,并用npx @redocly/cli lint做零报错硬门禁。AI 经常把 OpenAPI 3.0 的nullable: true混进 3.1 文档(3.1 全面兼容 JSON Schema 2020-12,应写type: ["string", "null"]),也容易拼错$ref路径;每次生成完必须让 Codex 自己跑通 Redocly 校验直到零错误。 - 坚持「源码实证」原则:禁止模型脑补任何未在代码里出现的字段与错误码。在提示词和
AGENTS.md中要求 Codex 必须结合校验器(Zod / Pydantic / Go Struct Tag / Jakarta Validation)和全局异常处理类推导 Schema,源码模糊处用x-needs-review: true显式标记待人工核对。 - 交付给 Postman 与 Apifox 时,以校验通过的
openapi.yaml为唯一真相源。Postman 与 Apifox 均支持直接导入标准 OpenAPI 3.1 文档并自动建目录与模型;若测试团队需要自带变量和状态断言的现成冒烟集合,再让 Codex 配套导出 Postman Collection v2.1 与仅含占位符的环境变量 JSON(严禁写入真实生产 Token)。 - 全仓库反向梳理几十条接口、跨控制器追踪多层 DTO 与错误枚举非常消耗长上下文与推理配额。国内若缺少外币卡或原套餐窗口经常触顶,可在本站按需开通 ChatGPT Plus 充值 或高配额 ChatGPT Pro 充值,团队多人联调可了解 ChatGPT Business 团队定制。

图:本站根据 OpenAPI 3.1 规范 与 Redocly 文档 整理的示意图
本文根据 OpenAPI 官方规范《OpenAPI Specification v3.1.0》、Redocly 官方文档《redocly lint》、Postman 官方文档《Importing from OpenAPI》及 OpenAI Codex 官方文档《Codex CLI》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 接手历史 Express、Go Gin、Spring Boot 或 PHP 老项目,面临接口零文档、前后端联调全靠口头问和翻源码的工程师;
- 试过直接让 AI 写 Swagger / OpenAPI YAML,结果拿到一堆损坏的
$ref引用、混用 3.0 与 3.1 语法、或者凭空编造请求字段的开发者; - 希望一键产出通过严格校验的
openapi.yaml,并顺畅导入 Postman 或 Apifox 给前端、测试团队直接发请求联调的研发团队。
一、第一步先盘点接口清单,再在 AGENTS.md 锁死契约规范
在生成正式 YAML 前,先把以下文档生成规范写入仓库 AGENTS.md(若为大型多服务仓库可配合子目录分层配置,见 /guides/codex-large-monorepo-layered-agents-md-scoped-test-guide):
markdown
# OpenAPI 3.1 接口文档生成约束(AGENTS.md)
## 规范与溯源红线
- 文档版本严格锁定 `openapi: 3.1.0`;可空字段使用 JSON Schema 2020-12 语法(`type: ["string", "null"]`),禁止混用 3.0 废弃的 `nullable: true`。
- 每个字段的类型、必填项(`required`)、枚举值与 4xx/5xx 错误响应必须能在仓库路由、校验器或全局异常处理器中找到源码依据;无法确认时显式添加 `x-needs-review: true` 并附源码位置注释,禁止凭空编造。
- 所有可复用数据结构与错误信封统一抽到 `components.schemas`,全局鉴权抽到 `components.securitySchemes`。
## 交付与校验门禁
- 生成或更新 `docs/openapi.yaml` 后,必须执行 `npx @redocly/cli lint docs/openapi.yaml` 直至 0 errors。
- 配套导出的 `docs/postman_environment.json` 仅允许填写 `{{baseUrl}}`、`REPLACE_WITH_DEV_TOKEN` 等占位符,严禁写入任何真实密钥或线上域名凭据。
二、实战两段式提示词:从源码提取到 Redocly 零错通过
阶段 1:扫描并输出接口盘点表(Plan Mode / 只读审查)
text
请先只读扫描 src/routes/、src/controllers/、src/middlewares/auth* 与全局错误处理中间件,先不要生成 YAML,输出一份 `docs/endpoint-inventory.md` 盘点表:
1. 列出路由前缀挂载关系、全局统一响应信封格式(如 code/data/message)与鉴权头名称;
2. 按业务标签分组列出每条接口的 Method、完整 Path、鉴权要求、请求校验文件位置与响应结构文件位置;
3. 单独标注出缺少显式类型定义或动态返回 JSON 的遗留接口,等我确认范围后再进入 OpenAPI 3.1 生成。
阶段 2:按模块生成 docs/openapi.yaml 并跑通 Lint 校验
text
请基于刚才确认的 `docs/endpoint-inventory.md`,对照真实源码生成 `docs/openapi.yaml`(OpenAPI 3.1.0):
1. 为每个接口补齐唯一的 `operationId`、简明中文 `summary`、标签分组 `tags`、路径/查询/请求体参数、真实可用的 `examples` 以及 200/400/401/403/404/422 响应结构;
2. 所有公共 DTO、分页结构与统一错误体全部抽入 `components.schemas` 用 `$ref` 复用;
3. 写完后运行 `npx @redocly/cli lint docs/openapi.yaml`,逐条修掉所有 Schema 语法错误、断链 `$ref` 和重名 `operationId`,直到零 Error 输出;
4. 同步生成一份可导入 Postman 与 Apifox 的 `docs/postman_collection.json`(Collection v2.1,含基础状态码测试脚本)和脱敏版 `docs/postman_environment.json`。
订阅与账号准备提示:反向梳理数十个老接口并反复跑 Redocly 规范校验、同步导出测试集合,属于典型的多文件重上下文任务(额度与省额方法见 /guides/codex-save-usage-quota-model-reasoning-context-tips)。重度接口治理与全栈联调推荐按需选用 ChatGPT Pro 5x iOS 可覆盖档 或 ChatGPT Pro 5x 信用卡不可覆盖档;新账号注册遇到手机验证环节可查看 Codex 注册手机验证服务。
三、导入 Postman 与 Apifox 的最佳协作姿势
拿到校验通过的文档后,按团队协作需要决定直接导入 OpenAPI 还是导入派生集合:

图:本站根据 Postman 导入文档 与团队联调经验整理的示意图
具体操作非常轻量:在 Postman 中点击左上角 Import 选择 docs/openapi.yaml 即可自动生成带目录与示例值的 Collection;在 Apifox 中进入项目「项目设置 → 导入数据 → OpenAPI / Swagger」选择该文件并开启按接口路径增量覆盖即可。随后还可以把这份 openapi.yaml 作为前后端类型生成的唯一契约(详见 /guides/codex-fullstack-api-openapi-contract-type-alignment-guide),并把 npx @redocly/cli lint 放进 CI 防止文档再次腐烂。
常见问题
问:项目接口超过 100 个,一次性生成 openapi.yaml 上下文装不下怎么办?
答:千万不要把上百个接口硬塞进一轮对话。本站建议采用多文件拆分结构:先建根文件 docs/openapi.yaml(放 info、servers、securitySchemes 与公共 schemas),再按业务域拆出 docs/paths/orders.yaml、docs/paths/users.yaml 等子文件逐批让 Codex 生成,最后用 npx @redocly/cli bundle docs/openapi.yaml -o docs/openapi.bundled.yaml 合并成单文件导入 Postman 或 Apifox。
问:反向生成的文档怎么防止过两个月业务代码改了、文档又过期?
答:最省心的做法是在仓库 AGENTS.md 里追加一条规则:凡是修改了路由路径、请求校验器或响应 DTO,Codex 在同一笔改动里必须同步更新对应 docs/openapi.yaml 片段并跑通 Redocly 校验;如果原本框架(如 FastAPI、Springdoc)本身支持代码注解导出 OpenAPI,也可以用 Codex 反向补齐缺失注解,让文档彻底由构建流水线自动产出。
问:用 Codex 治理大项目接口文档、做全栈联调很耗额度,个人或团队怎么开通高配额订阅、能否开增值税发票?
答:可前往本站 AI 会员充值总览 按需选购 ChatGPT Plus 充值、ChatGPT Plus 自助卡密 或更高额度的 ChatGPT Pro 充值,团队多人联调采购可了解 ChatGPT Business 团队定制。支持支付宝、微信支付和 AlipayHK,自助卡密无需提供账号密码,并支持开具增值税发票;实时价格与规格以页面展示为准,售后执行掉订阅按剩余天数折退、封号不在质保范围规则。
相关教程
- 用 Codex 做全栈接口联调与前后端类型对齐:先生成 OpenAPI 契约再改代码
- Codex 接手大型 Monorepo 项目怎么配:子目录分层 AGENTS.md 与局部测试技巧
- Codex 写代码时爱删测试或乱改无关文件怎么办:5 条 AGENTS.md 硬约束护栏
- Codex 额度消耗太快怎么省:模型档位切换、推理强度降级与控上下文 6 招
参考资料
- OpenAPI Initiative:OpenAPI Specification v3.1.0 — https://spec.openapis.org/oas/v3.1.0
- Redocly 官方文档:redocly lint command — https://redocly.com/docs/cli/commands/lint
- Postman 官方文档:Import an OpenAPI definition — https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-from-openapi/
- OpenAI Codex 官方文档:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
0 条评论
还没有评论,来抢沙发~