企业官网建设流程全解析

不再猜 OpenAI API 参数：3步用openai-openapi查清每个接口

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

openai-openapi 是官方发布的 OpenAI API 的 OpenAPI 3.1 规范仓库，里面写清了每个接口的参数、请求体和响应结构。它适合想在调用前用可视化方式核对参数、生成类型化客户端、或想理解错误码语义的开发者。跟着本文走一遍，3 步就能在自己电脑上跑起来。

调用前先查参数是不是枚举值

假设你正在接一个内容审核场景，想调用 Moderations 接口，但不确定input到底收字符串还是数组；或者调/responses连续撞了 429，不知道重试该等多久。翻网页文档要开好几个标签页，而 openai-openapi 把接口的 schema、请求示例、响应示例都写在一个 YAML 文件里，直接搜索字段名就能看到答案。

三步上手：从克隆到本地文档站

第 1 步：克隆规范仓库

先跑这条命令，把规范文件拉到本地：

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

仓库结构很克制：openapi.yaml 和 openapi.json 两份等价规范，外加几个说明文档。日常用 YAML 这份即可。

第 2 步：把 openapi.yaml 导入本地文档站

规范用的是 OpenAPI 3.1，任何支持该版本的工具都能导入。用 Docker 起一个 Swagger UI 最省事：

docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml -v "$PWD":/spec swaggerapi/swagger-ui

浏览器打开http://localhost:8080，就能看到按 Assistants、Audio、Chat、Responses 等标签分组的接口列表。Redoc 这类静态文档工具同样支持，换工具时把文件路径指过去就行。

第 3 步：挑一个端点，30 秒验证规范是否生效

在文档站里搜listAssistants，效果如下——端点、查询参数、默认值一目了然：

/assistants: get: operationId: listAssistants summary: List assistants parameters: - name: limit in: query schema: type: integer default: 20

能搜到、参数类型和默认值都对得上，说明规范导入成功了。

规范里藏着的 3 个细节

每个端点自带多语言请求示例

规范里很多操作挂了x-oaiMeta.examples字段，curl、python、javascript 的请求示例和响应示例直接写在 YAML 里。还是以listAssistants为例，同一段规范里就有可复制的 Python 代码：

from openai import OpenAI client = OpenAI() my_assistants = client.beta.assistants.list( order="desc", limit="20", ) print(my_assistants.data)

也就是说写请求前不用切换标签页找文档，端点定义旁边就是示例。

429 错误码附带了重试策略

多数规范只写"429：请求过多"，这份文件把components/responses里的限流错误拆成了三种：TooManyRequests、InferenceRateLimited、InferenceServiceUnavailable，并且都带Retry-After响应头的定义。后两种还解释了语义——slow_down表示你的请求速率增长太快，要降速再逐步加回；server_is_overloaded表示模型侧暂时过载，稍等重试即可。做重试逻辑时直接照这个语义写分支，比只盯状态码可靠。

官方 SDK 全部由这份规范生成

README 里列了 Python、JavaScript/TypeScript、.NET、Go、Java、Ruby 六套官方 SDK，它们都是从这份规范生成的。这意味着规范是唯一的真身：接口参数以规范为准，SDK 行为与规范对不上时，多半是该报 issue 了，而不是自己绕过去。

3 个容易踩的坑，提前说

1. 改了 openapi.yaml 提交 PR 会被 CI 拒绝现象：你本地改了两行参数描述，提 PR 后直接挂掉。原因：这两份文件是从上游源自动生成并同步的产物，仓库的 "Generated files unchanged" CI 检查会拒绝任何对它们的改动（CONTRIBUTING.md 里写明了）。解决：别直接改文件，把版本号、端点 + HTTP 方法、期望行为和合成数据的示例整理好，用 issue 反馈，官方会在上游源修正后自动同步过来。

2. 接口调用报错，实际是缺了 Beta 版本头现象：照着规范调用 Assistants 相关端点，返回不符合预期的结果。原因：规范里该模块的示例请求带了OpenAI-Beta: assistants=v2这类头，且部分端点标了deprecated: true。解决：对照x-oaiMeta.examples里的请求头补全，调用前顺手看一眼有没有 deprecated 标记。

3. 报 schema 问题被搁置，多数是信息不全现象：issue 提了"这个字段不对"，长期没人处理。原因：官方要求报告包含受影响的版本号、端点和 HTTP 方法或 schema、期望行为、以及用合成数据写的最小示例，并且不能带 API key、客户数据或私有 URL。解决：按这个清单自查一遍再提交；如果疑似安全漏洞，走 SECURITY.md 的私有渠道，不要发公开 issue。

适合谁，以及下一步

如果你要给 OpenAI API 生成客户端、搭内部接口文档站，或只是想在发请求前确认参数类型和重试语义，这个仓库就是起点。下一步建议直接打开 openapi.yaml，搜一个你明天就要调用的operationId，把它的参数和示例从头到尾读一遍。

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