一文看懂 openai-openapi：3 步读懂 OpenAI API 官方 OpenAPI 规范，不再靠猜参数

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi

openai-openapi 是 OpenAI 官方的 OpenAPI 3.1 规范仓库，核心文件openapi.yaml与openapi.json完整描述了全部接口、认证方式、参数及请求响应结构。无论你是在写调用 OpenAI API 的代码，还是搭建客户端生成、接口测试这类工具，都可以把它当作一份唯一可靠的参照源，不必再东拼西凑各种零散说明。

先给结论：这份 OpenAPI 规范为什么值得看

结论放在前面：它比网页版接口手册更稳定，比教程文章更精确。

• 机器可读。openapi.yaml遵循标准 OpenAPI 3.1（info 中声明的版本号为 2.3.0），任何支持 OpenAPI 生态的工具都能直接导入：浏览、生成代码、配置测试平台都走同一份文件。
• 它是官方 SDK 的源头。Python、JavaScript/TypeScript、.NET、Go、Java、Ruby 的官方 SDK 均由这份规范生成，规范即接口行为的基准。
• 自动同步更新。README 明确说明这两个文件是由上游源自动同步的生成产物，你拿到的始终是官方发布的最新版本。

3 步打开并理解文档

第 1 步：拿到文件

克隆仓库到本地，或直接在线浏览文件内容：

git clone https://gitcode.com/GitHub_Trending/op/openai-openapi

第 2 步：先读开头前 60 行

openapi.yaml的开头会回答三个问题：规范版本（3.1.0）、服务地址（https://api.openai.com/v1）、认证方式（securitySchemes中定义的 Bearer 令牌ApiKeyAuth）。这三处是全局固定信息，几分钟后你对整份文档就有了框架感。

第 3 步：用 tags 当目录跳转

文档用 17 个 tag 划分功能模块。遇到具体问题，先判断它属于哪个模块，再跳到对应路径下看参数与响应定义，不需要通读全文。

从文档里读出 OpenAI API 能力地图

tags字段本身就是一张能力地图：共 17 个模块，覆盖“调用模型、加工数据、校验结果”的常见场景。

这里建议留意deprecated: true标记：文档里有 60 多处接口被标记弃用，部分 Assistants 相关接口在其中，且/chat/completions的说明里也提示新项目可优先考虑 Responses 接口。选型前先看一眼弃用标记，能少走弯路。

一个最小场景：从字段定义到实际调用

以使用频率最高的POST /chat/completions为例（operationId：createChatCompletion）。它的请求体引用CreateChatCompletionRequest模式，其中两个必填字段一眼可见：

• model：模型标识，字符串
• messages：消息数组，minItems: 1，至少包含一条消息

对应的最小请求体如下：

{ "model": "gpt-4o-mini", "messages": [ { "role": "user", "content": "用一句话解释什么是 OpenAPI" } ] }

参数构造完，再看 responses 段：200返回 Chat Completion 对象；若stream为true，响应切换为 server-sent events（SSE），最后一帧是字面文本[DONE]。很多新手流式解析“卡住”的疑问，答案就写在这一行。

另外注意：接口描述里写明不同模型对参数的支持并不一致（较新的推理模型是典型例子）。参数报错时，先确认目标模型是否支持该参数，再怀疑自己的代码。

新手常见坑与处理建议

总结与资源入口

把 openai-openapi 当“产品说明书”：查字段看规范，懂维护机制看 README，比任何二手教程都可靠。📌

• 完整规范：openapi.yaml、openapi.json
• 仓库说明与反馈流程：README.md
• 贡献与安全政策：CONTRIBUTING.md、SECURITY.md

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi