openai-openapi：一份机器可读的 OpenAI REST API 完整描述文档
【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi
调用 OpenAI API 时，你是否要在零散文档里逐个核对参数名、请求头和响应字段？openai-openapi 是 OpenAI 发布的官方 OpenAPI 规范仓库，它用 OpenAPI 3.1 格式（一种描述 REST 接口的行业标准）把接口端点、认证方式、请求参数和响应结构写成了一份机器可读的文档。这篇文章会讲清楚：它是什么、能用来做什么、怎么接入，以及使用前的几个注意点。
上图是 OpenAI 官方 API 参考页面的样式（仓库 README 中随附的截图）。这个规范文件描述的内容，和这类在线参考页是同一套接口定义——区别在于它是以文件形式发布、可以被工具直接消费的版本。
它解决什么问题
一句话：它是 OpenAI API 的“接口事实清单”。
- OpenAI 平台包含对话、音频、图像、批量任务、微调等大量端点，且功能持续更新。人工阅读网页文档容易遗漏细节，而规范文件把每个端点的参数类型、是否必填、默认值、枚举取值都明确写出。
- 网页文档是给人看的，
openapi.yaml/openapi.json是给工具用的。客户端生成器、测试平台、API 网关都能直接解析它。 - 仓库同时提供 YAML 和 JSON 两种格式，内容一致，按你的工具偏好选用即可。
文档里都有什么
根据规范文件本身，文档头部声明了 API 版本 2.3.0、服务地址api.openai.com/v1，以及基于 API 密钥的认证方式（ApiKeyAuth）。
内容按 16 个功能标签（tags字段）组织。按使用场景大致可以这样理解：
| 你关心的场景 | 规范中对应的模块 |
|---|---|
| 对话、补全、模型响应 | Chat、Completions、Responses、Models |
| 多模态输入输出 | Audio（语音转写/合成）、Images（生成/编辑） |
| 向量与文件 | Embeddings、Files、Uploads |
| 大规模异步处理 | Batch |
| 训练与评估 | Fine-tuning、Evals、Graders |
| 会话与助手状态 | Assistants、Conversations |
| 安全与合规 | Moderations、Audit Logs |
每个模块下又细分到具体端点，例如/chat/completions、/audio/speech、/fine_tuning/jobs等，均包含请求体、响应 schema 和错误说明。你可以直接在 openapi.yaml 中按标签定位。
拿到这份文档能做什么
生成类型化客户端
README 说明，OpenAI 官方 SDK（Python、JavaScript/TypeScript、.NET、Go、Java、Ruby）都是基于这份规范生成的。这意味着：如果你不用官方 SDK，也可以用它为自己的语言或框架生成带类型提示的调用代码，参数拼写错误会在编译期暴露，而不是等接口返回 400 才发现。
搭建交互式 API 浏览器
任何支持 OpenAPI 生态的工具（如 Swagger UI、Redoc 这类文档渲染器）都可以导入该文件，生成带请求试跑的本地参考页面，方便团队成员自助查询，不必反复翻在线文档。
驱动测试与契约校验
你可以把规范导入 API 测试工具，按其中定义的响应 schema 断言真实返回结构。当 OpenAI 更新接口后，重新拉取规范对比差异，就能提前发现哪些字段变了。
快速上手
克隆仓库（规范文件体积较大，建议直接取用而非下载压缩包）：
git clone https://gitcode.com/GitHub_Trending/op/openai-openapi打开 openapi.yaml 或 openapi.json，确认
info.version是否为你需要核对的版本。将文件导入你使用的 OpenAPI 工具，或交给客户端代码生成器。
若只是核对参数，直接搜索对应的
operationId（如createChatCompletion）通常比翻端点路径更快。
使用前的边界与限制
- 它是接口描述，不是使用教程。README 明确建议：需要讲解、示例和指南时去查阅 OpenAI 的人读文档，规范文件只回答“参数叫什么、什么类型、返回什么”。
- 这两个规范文件是生成产物，由上游源自动同步。根据 AGENTS.md，直接修改
openapi.yaml或openapi.json不会更新上游源，CI 也会拒绝此类改动。 - 对外贡献者不能提交 Pull Request。发现 schema 错误、字段缺失等问题时，按 README.md 的反馈流程提 issue，并附上涉及的端点、预期行为和最小合成示例；安全类问题应通过 SECURITY.md 私下报告。
- 部分端点已标记废弃（例如 Assistants 相关接口在规范中带有
deprecated: true）。在基于规范做集成前，建议确认目标端点的废弃状态，避免踩到即将下线的接口。
下一步可以做什么
- 如果你已在用官方 SDK：把规范当作参数与返回字段的核对清单，尤其在升级模型或功能时。
- 如果你在封装面向内部的 AI 平台：用它生成客户端代码和 mock 服务，可以在不消耗真实 API 额度的情况下先跑通链路。
- 如果你在维护回归测试：把规范版本纳入测试基线，接口变更时先对比 diff 再调整用例。
总的来说，openai-openapi 的价值不在于“多一个文档”，而在于让 OpenAI API 的所有接口细节进入了可解析、可对比、可自动化的工作流。LICENSE 为 MIT 许可，可放心用于内部工具链。
【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
