OpenAI-OpenAPI免费资源：零成本学习API规范的途径

gitblog_00001

856人浏览 · 2025-09-29 03:25:59

gitblog_00001 · 2025-09-29 03:25:59 发布

OpenAI-OpenAPI免费资源：零成本学习API规范的途径

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

你是否还在为找不到高质量的API规范学习材料而烦恼？是否希望能够通过实际案例来深入理解OpenAPI规范？本文将为你介绍一个零成本学习API规范的绝佳途径——OpenAI-OpenAPI项目，通过这个开源项目，你可以免费获取到OpenAI API的最新OpenAPI规范，从而深入学习和掌握API设计的最佳实践。

读完本文后，你将能够：

了解OpenAI-OpenAPI项目的基本情况和主要内容
掌握如何获取和使用项目中的OpenAPI规范文件
学会如何通过实际案例来学习API规范
了解项目中提供的各种编程语言的示例代码

项目概述

OpenAI-OpenAPI项目是一个开源项目，主要提供OpenAI API的OpenAPI规范。项目路径为[项目仓库地址]，你可以通过以下命令来克隆该项目：

git clone [项目仓库地址]

项目中包含以下几个主要文件：

LICENSE：项目许可证文件
README.md：项目说明文档
openapi.documented.yml：OpenAPI规范文件

OpenAPI规范文件详解

openapi.documented.yml是项目的核心文件，其中定义了OpenAI API的完整规范。该文件采用YAML格式编写，遵循OpenAPI 3.1.0规范。

规范文件基本结构

OpenAPI规范文件通常包含以下几个主要部分：

openapi：指定OpenAPI规范的版本号
info：包含API的基本信息，如标题、描述、版本等
servers：定义API的服务器地址
paths：定义API的各个端点及其操作
components：定义可重用的组件，如模式、参数等

以下是openapi.documented.yml文件中的基本信息部分：

openapi: 3.1.0
info:
  title: OpenAI API
  description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.
  version: 2.3.0
  termsOfService: https://openai.com/policies/terms-of-use
  contact:
    name: OpenAI Support
    url: https://help.openai.com/
  license:
    name: MIT
    url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
  - url: https://api.openai.com/v1

API端点定义

在paths部分，定义了OpenAI API的各个端点及其支持的操作。例如，/assistants端点支持GET和POST两种操作，分别用于列出助手和创建助手。

以下是/assistants端点的GET操作定义：

/assistants:
  get:
    operationId: listAssistants
    tags:
      - Assistants
    summary: List assistants
    parameters:
      - name: limit
        in: query
        description: >
          A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
          default is 20.
        required: false
        schema:
          type: integer
          default: 20
      - name: order
        in: query
        description: >
          Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for
          descending order.
        schema:
          type: string
          default: desc
          enum:
            - asc
            - desc
    responses:
      '200':
        description: OK
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListAssistantsResponse'

数据模型定义

在components/schemas部分，定义了API中使用的数据模型。例如，AssistantObject模型定义了助手对象的结构：

components:
  schemas:
    AssistantObject:
      type: object
      properties:
        id:
          type: string
          description: The identifier, which can be referenced in API endpoints.
        object:
          type: string
          enum:
            - assistant
          description: The object type, which is always `assistant`.
        created_at:
          type: integer
          format: int64
          description: The Unix timestamp (in seconds) for when the assistant was created.
        name:
          type: string
          nullable: true
          description: The name of the assistant. The maximum length is 256 characters.
        description:
          type: string
          nullable: true
          description: The description of the assistant. The maximum length is 512 characters.
        model:
          type: string
          description: ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.
        instructions:
          type: string
          nullable: true
          description: The system instructions that the assistant uses. The maximum length is 32768 characters.

多语言示例代码

OpenAPI规范文件中还提供了多种编程语言的示例代码，帮助开发者快速上手使用OpenAI API。以下是一些主要编程语言的示例：

Python示例

from openai import OpenAI

client = OpenAI(
    api_key="My API Key",
)
assistant = client.beta.assistants.create(
    model="gpt-4o",
)
print(assistant.id)

Node.js示例

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'My API Key',
});

const assistant = await client.beta.assistants.create({ model: 'gpt-4o' });

console.log(assistant.id);

Java示例

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.assistants.Assistant;
import com.openai.models.beta.assistants.AssistantCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        AssistantCreateParams params = AssistantCreateParams.builder()
            .model(ChatModel.GPT_5)
            .build();
        Assistant assistant = client.beta().assistants().create(params);
    }
}

API端点使用示例

下面以创建助手为例，详细介绍如何使用OpenAPI规范中定义的API端点。

创建助手的API端点

创建助手的API端点定义如下：

/assistants:
  post:
    operationId: createAssistant
    tags:
      - Assistants
    summary: Create assistant
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAssistantRequest'
    responses:
      '200':
        description: OK
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantObject'

请求示例

以下是使用curl命令创建助手的示例：

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    "name": "Math Tutor",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o"
  }'

响应示例

成功创建助手后，API将返回以下响应：

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}