oas-api-spec-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OAS Third-Party API Spec Generator

OAS第三方API规范生成器

A skill for generating OpenAPI Specification 3.2.0 documents for third-party APIs (Microsoft, Google, OpenAI, Anthropic, Stripe, GitHub, Slack, AWS, and more).

一个用于为第三方API（Microsoft、Google、OpenAI、Anthropic、Stripe、GitHub、Slack、AWS等）生成OpenAPI Specification 3.2.0文档的Skill。

When to Use This Skill

何时使用此Skill

Use this skill when the user asks to:

Generate an OpenAPI spec for a third-party API
Create OAS/Swagger definitions for external services
Document third-party API endpoints they're integrating with
Convert API documentation into OpenAPI format
Build client SDKs from third-party API specs
Create API gateway configurations for external APIs

Trigger phrases: "create OAS for", "generate openapi spec", "openapi for [provider]", "swagger spec for", "API spec for"

当用户提出以下需求时，使用此Skill：

为第三方API生成OpenAPI规范
为外部服务创建OAS/Swagger定义
记录他们正在集成的第三方API端点
将API文档转换为OpenAPI格式
从第三方API规范构建客户端SDK
为外部API创建API网关配置

触发短语："create OAS for"、"generate openapi spec"、"openapi for [provider]"、"swagger spec for"、"API spec for"

How This Skill Works

此Skill的工作方式

Step 1: Identify the Target API

步骤1：确定目标API

When the user requests a spec for a third-party API, identify:

Provider (e.g., OpenAI, Microsoft Graph, Google Cloud, Stripe)
Specific endpoints/services needed (e.g., "just the Chat Completions endpoint" vs "the full API")
Use case (SDK generation, API gateway, documentation, testing)

当用户请求第三方API的规范时，需明确：

提供商（例如：OpenAI、Microsoft Graph、Google Cloud、Stripe）
所需的特定端点/服务（例如：“仅Chat Completions端点” vs “完整API”）
使用场景（SDK生成、API网关、文档、测试）

Step 2: Fetch Current API Documentation

步骤2：获取最新API文档

Use WebFetch to pull the latest API documentation from the provider:

Provider documentation URLs (use these as starting points):

OpenAI:         https://platform.openai.com/docs/api-reference
Anthropic:      https://docs.anthropic.com/en/api
Google AI:      https://ai.google.dev/api/rest
Microsoft Graph: https://learn.microsoft.com/en-us/graph/api/overview
Azure OpenAI:   https://learn.microsoft.com/en-us/azure/ai-services/openai/reference
Stripe:         https://stripe.com/docs/api
GitHub:         https://docs.github.com/en/rest
Slack:          https://api.slack.com/methods
AWS (various):  https://docs.aws.amazon.com/
Twilio:         https://www.twilio.com/docs/usage/api
SendGrid:       https://docs.sendgrid.com/api-reference
Cloudflare:     https://developers.cloudflare.com/api/
Vercel:         https://vercel.com/docs/rest-api
Supabase:       https://supabase.com/docs/reference
Firebase:       https://firebase.google.com/docs/reference/rest

Also check if the provider publishes an official OpenAPI spec:

Official OpenAPI specs (fetch and use as reference/base):

OpenAI:          https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml
GitHub:          https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml
Stripe:          https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml
Microsoft Graph: https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml
Anthropic:       https://raw.githubusercontent.com/anthropics/anthropic-sdk-python/main/api.yaml (if available)

If an official spec exists, fetch it and upgrade/adapt it to OAS 3.2.0 rather than writing from scratch.

使用WebFetch从提供商处获取最新的API文档：

提供商文档URL（以此为起点）：

OpenAI:         https://platform.openai.com/docs/api-reference
Anthropic:      https://docs.anthropic.com/en/api
Google AI:      https://ai.google.dev/api/rest
Microsoft Graph: https://learn.microsoft.com/en-us/graph/api/overview
Azure OpenAI:   https://learn.microsoft.com/en-us/azure/ai-services/openai/reference
Stripe:         https://stripe.com/docs/api
GitHub:         https://docs.github.com/en/rest
Slack:          https://api.slack.com/methods
AWS (various):  https://docs.aws.amazon.com/
Twilio:         https://www.twilio.com/docs/usage/api
SendGrid:       https://docs.sendgrid.com/api-reference
Cloudflare:     https://developers.cloudflare.com/api/
Vercel:         https://vercel.com/docs/rest-api
Supabase:       https://supabase.com/docs/reference
Firebase:       https://firebase.google.com/docs/reference/rest

同时检查提供商是否发布了官方OpenAPI规范：

官方OpenAPI规范（获取并作为参考/基础）：

OpenAI:          https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml
GitHub:          https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml
Stripe:          https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml
Microsoft Graph: https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml
Anthropic:       https://raw.githubusercontent.com/anthropics/anthropic-sdk-python/main/api.yaml（若可用）

如果存在官方规范，获取并将其升级/适配为OAS 3.2.0，而非从头编写。

Step 3: Generate the OAS 3.2.0 Spec

步骤3：生成OAS 3.2.0规范

Generate a spec following the structure and patterns defined below. Always output as YAML (more readable than JSON for specs).

按照以下定义的结构和模式生成规范。始终以YAML格式输出（对于规范而言，YAML比JSON更具可读性）。

Step 4: Validate

步骤4：验证

After generating, validate the spec structure against OAS 3.2.0 rules (see Validation section below).

生成后，根据OAS 3.2.0规则验证规范结构（见下文验证部分）。

OAS 3.2.0 Spec Structure

OAS 3.2.0规范结构

Every generated spec MUST follow this top-level structure:

yaml

openapi: 3.2.0

info:
  title: "{Provider Name} API"
  version: "{API version from provider docs}"
  description: |
    OpenAPI 3.2.0 specification for the {Provider Name} API.
    Auto-generated from official documentation.

    Source: {documentation URL}
    Generated: {date}
  contact:
    name: "{Provider Name} API Support"
    url: "{provider support URL}"
  license:
    name: "API Terms of Service"
    url: "{provider ToS URL}"
  x-generated-by: "OAS API Spec Generator Skill"
  x-source-documentation: "{documentation URL}"

servers:
  - url: "{base URL}"
    description: "Production"
  # Add sandbox/staging if available

security:
  - {default security scheme}: []

tags:
  # Use structured tags (OAS 3.2 feature)
  - name: "{Resource Group}"
    summary: "{Description}"
    kind: resource  # or: operation, webhook, admin
    # parent: "{Parent Tag}"  # For hierarchical grouping

paths:
  # Endpoint definitions...

webhooks:
  # If the API supports webhooks...

components:
  schemas:
    # Data models...
  parameters:
    # Reusable parameters...
  responses:
    # Standard error responses...
  securitySchemes:
    # Auth methods...
  mediaTypes:
    # Reusable media types (OAS 3.2 feature)

externalDocs:
  description: "Official {Provider} API Documentation"
  url: "{docs URL}"

每个生成的规范必须遵循以下顶层结构：

yaml

openapi: 3.2.0

info:
  title: "{Provider Name} API"
  version: "{API version from provider docs}"
  description: |
    OpenAPI 3.2.0 specification for the {Provider Name} API.
    Auto-generated from official documentation.

    Source: {documentation URL}
    Generated: {date}
  contact:
    name: "{Provider Name} API Support"
    url: "{provider support URL}"
  license:
    name: "API Terms of Service"
    url: "{provider ToS URL}"
  x-generated-by: "OAS API Spec Generator Skill"
  x-source-documentation: "{documentation URL}"

servers:
  - url: "{base URL}"
    description: "Production"
  # 若可用，添加沙箱/预发布环境

security:
  - {default security scheme}: []

tags:
  # 使用结构化标签（OAS 3.2特性）
  - name: "{Resource Group}"
    summary: "{Description}"
    kind: resource  # 或: operation, webhook, admin
    # parent: "{Parent Tag}"  # 用于层级分组

paths:
  # 端点定义...

webhooks:
  # 若API支持webhooks...

components:
  schemas:
    # 数据模型...
  parameters:
    # 可复用参数...
  responses:
    # 标准错误响应...
  securitySchemes:
    # 认证方式...
  mediaTypes:
    # 可复用媒体类型（OAS 3.2特性）

externalDocs:
  description: "Official {Provider} API Documentation"
  url: "{docs URL}"

Provider-Specific Auth Patterns

提供商特定的认证模式

Bearer Token (API Key as Bearer)

Bearer Token（作为Bearer的API密钥）

Used by: OpenAI, Anthropic, Cohere, Mistral

yaml

components:
  securitySchemes:
    apiKeyBearer:
      type: http
      scheme: bearer
      description: |
        API key passed as Bearer token.
        Obtain from: {provider dashboard URL}

security:
  - apiKeyBearer: []

使用方：OpenAI、Anthropic、Cohere、Mistral

yaml

components:
  securitySchemes:
    apiKeyBearer:
      type: http
      scheme: bearer
      description: |
        作为Bearer令牌传递的API密钥。
        获取地址：{provider dashboard URL}

security:
  - apiKeyBearer: []

Custom Header API Key

自定义Header API密钥

Used by: Anthropic (x-api-key), OpenAI (also supports this)

yaml

components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: "x-api-key"
      description: |
        API key passed in custom header.
        Obtain from: {provider dashboard URL}

使用方：Anthropic（x-api-key）、OpenAI（也支持此方式）

yaml

components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: "x-api-key"
      description: |
        在自定义Header中传递的API密钥。
        获取地址：{provider dashboard URL}

OAuth 2.0 Authorization Code

OAuth 2.0授权码

Used by: Microsoft Graph, Google APIs, GitHub, Slack, Stripe Connect

yaml

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: "{auth URL}"
          tokenUrl: "{token URL}"
          refreshUrl: "{refresh URL}"
          scopes:
            "scope.read": "Read access"
            "scope.write": "Write access"
      # OAS 3.2: OAuth2 metadata URL
      x-oauth2-metadata-url: "{provider}/.well-known/oauth-authorization-server"

使用方：Microsoft Graph、Google APIs、GitHub、Slack、Stripe Connect

yaml

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: "{auth URL}"
          tokenUrl: "{token URL}"
          refreshUrl: "{refresh URL}"
          scopes:
            "scope.read": "Read access"
            "scope.write": "Write access"
      # OAS 3.2: OAuth2元数据URL
      x-oauth2-metadata-url: "{provider}/.well-known/oauth-authorization-server"

OAuth 2.0 Client Credentials

OAuth 2.0客户端凭据

Used by: Microsoft Graph (app-only), AWS Cognito, Auth0

yaml

components:
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "{token URL}"
          scopes:
            ".default": "Default scope"

使用方：Microsoft Graph（仅应用）、AWS Cognito、Auth0

yaml

components:
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "{token URL}"
          scopes:
            ".default": "Default scope"

AWS Signature V4

Used by: AWS services

yaml

components:
  securitySchemes:
    awsSigV4:
      type: apiKey
      in: header
      name: Authorization
      description: |
        AWS Signature Version 4.
        See: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
      x-amazon-apigateway-authtype: "awsSigv4"

使用方：AWS服务

yaml

components:
  securitySchemes:
    awsSigV4:
      type: apiKey
      in: header
      name: Authorization
      description: |
        AWS签名版本4。
        参考：https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
      x-amazon-apigateway-authtype: "awsSigv4"

Multi-Auth (Provider + Org)

多认证（提供商+组织）

Used by: OpenAI (API key + Organization header), Azure OpenAI (API key + Azure AD)

yaml

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
    orgHeader:
      type: apiKey
      in: header
      name: "OpenAI-Organization"
      description: "Optional organization ID"

使用方：OpenAI（API密钥+Organization头）、Azure OpenAI（API密钥+Azure AD）

yaml

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
    orgHeader:
      type: apiKey
      in: header
      name: "OpenAI-Organization"
      description: "可选组织ID"

Per-operation security can combine:

每个操作的安全配置可组合：

security:

- apiKey: []

orgHeader: []

---

---

Streaming Support (OAS 3.2.0)

流支持（OAS 3.2.0）

This is critical for AI API specs. OAS 3.2.0 has first-class streaming support.

这对AI API规范至关重要。OAS 3.2.0提供一流的流支持。

Server-Sent Events (SSE)

服务器发送事件（SSE）

Used by: OpenAI, Anthropic, Google AI (streaming responses)

yaml

paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      tags: [Chat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful response
          content:
            # Non-streaming response
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            # Streaming response (OAS 3.2 native)
            text/event-stream:
              schema:
                type: string
              itemSchema:
                $ref: '#/components/schemas/ChatCompletionChunk'
              x-stream-delimiter: "\n\n"

使用方：OpenAI、Anthropic、Google AI（流响应）

yaml

paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      tags: [Chat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful response
          content:
            # 非流响应
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            # 流响应（OAS 3.2原生支持）
            text/event-stream:
              schema:
                type: string
              itemSchema:
                $ref: '#/components/schemas/ChatCompletionChunk'
              x-stream-delimiter: "\n\n"

JSON Lines / NDJSON Streaming

JSON Lines / NDJSON流

Used by: Some batch/export APIs

yaml

responses:
  '200':
    content:
      application/x-ndjson:
        schema:
          type: string
        itemSchema:
          $ref: '#/components/schemas/BatchResultLine'

使用方：部分批量/导出API

yaml

responses:
  '200':
    content:
      application/x-ndjson:
        schema:
          type: string
        itemSchema:
          $ref: '#/components/schemas/BatchResultLine'

Common Response Patterns

常见响应模式

Paginated List Response

分页列表响应

Used by: Most REST APIs (Stripe, GitHub, Microsoft Graph)

yaml

components:
  schemas:
    # Cursor-based (Stripe, Slack)
    PaginatedList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/{Resource}'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true

    # Offset-based (GitHub, many REST APIs)
    PaginatedListOffset:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/{Resource}'
        total_count:
          type: integer
        page:
          type: integer
        per_page:
          type: integer

    # OData-style (Microsoft Graph)
    ODataCollection:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/{Resource}'
        '@odata.count':
          type: integer
        '@odata.nextLink':
          type: string
          format: uri
          nullable: true

使用方：大多数REST API（Stripe、GitHub、Microsoft Graph）

yaml

components:
  schemas:
    # 基于游标（Stripe、Slack）
    PaginatedList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/{Resource}'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true

    # 基于偏移量（GitHub、许多REST API）
    PaginatedListOffset:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/{Resource}'
        total_count:
          type: integer
        page:
          type: integer
        per_page:
          type: integer

    # OData风格（Microsoft Graph）
    ODataCollection:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/{Resource}'
        '@odata.count':
          type: integer
        '@odata.nextLink':
          type: string
          format: uri
          nullable: true

Standard Error Response

标准错误响应

yaml

components:
  schemas:
    # OpenAI/Anthropic style
    APIError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [message, type]
          properties:
            message:
              type: string
            type:
              type: string
              enum: [invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error, api_error]
            param:
              type: string
              nullable: true
            code:
              type: string
              nullable: true

    # Microsoft Graph style
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            innerError:
              type: object

    # Stripe style
    StripeError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum: [api_error, card_error, idempotency_error, invalid_request_error]
            message:
              type: string
            code:
              type: string
            param:
              type: string

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'

yaml

components:
  schemas:
    # OpenAI/Anthropic风格
    APIError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [message, type]
          properties:
            message:
              type: string
            type:
              type: string
              enum: [invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error, api_error]
            param:
              type: string
              nullable: true
            code:
              type: string
              nullable: true

    # Microsoft Graph风格
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            innerError:
              type: object

    # Stripe风格
    StripeError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum: [api_error, card_error, idempotency_error, invalid_request_error]
            message:
              type: string
            code:
              type: string
            param:
              type: string

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'

Provider Quick-Reference

提供商快速参考

When generating specs for these providers, use these specific patterns:

为以下提供商生成规范时，使用这些特定模式：

OpenAI API

Base URL:
```
https://api.openai.com
```
Auth: Bearer token (
```
Authorization: Bearer sk-...
```
)
Optional headers:
```
OpenAI-Organization
```
,
```
OpenAI-Project
```
Streaming: SSE with
```
stream: true
```
in request body

Key endpoints:

/v1/chat/completions

/v1/embeddings

/v1/images/generations

/v1/audio/transcriptions

/v1/models

/v1/files

/v1/assistants

/v1/threads

Official spec: Fetch from

https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml

Pagination: Cursor-based with
```
after
```
parameter
Versioning: Date-based via
```
OpenAI-Beta
```
header for beta features

基础URL:
```
https://api.openai.com
```
认证: Bearer令牌 (
```
Authorization: Bearer sk-...
```
)
可选Header:
```
OpenAI-Organization
```
、
```
OpenAI-Project
```
流: 请求体中设置
```
stream: true
```
的SSE

关键端点:

/v1/chat/completions

、

/v1/embeddings

、

/v1/images/generations

、

/v1/audio/transcriptions

、

/v1/models

、

/v1/files

、

/v1/assistants

、

/v1/threads

官方规范: 从

https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml

获取

分页: 基于
```
after
```
参数的游标分页
版本控制: 通过
```
OpenAI-Beta
```
Header的基于日期的版本控制（针对Beta功能）

Anthropic API

Base URL:
```
https://api.anthropic.com
```
Auth:
```
x-api-key
```
header +
```
anthropic-version
```
header (required, e.g.,
```
2024-10-22
```
)
Streaming: SSE with
```
stream: true
```

Key endpoints:

/v1/messages

/v1/messages/batches

/v1/models

Special: Tool use support, vision (base64 images), PDF support
Rate limits: Via
```
anthropic-ratelimit-*
```
headers
Pagination: Cursor-based

基础URL:
```
https://api.anthropic.com
```
认证:
```
x-api-key
```
Header + 必填的
```
anthropic-version
```
Header（例如：
```
2024-10-22
```
）
流: 设置
```
stream: true
```
的SSE

关键端点:

/v1/messages

、

/v1/messages/batches

、

/v1/models

特殊特性: 工具调用支持、视觉（Base64图片）、PDF支持
速率限制: 通过
```
anthropic-ratelimit-*
```
Header
分页: 基于游标的分页

Google AI (Gemini)

Base URL:

https://generativelanguage.googleapis.com

Auth: API key as query param (
```
?key=
```
) or OAuth2
Streaming: SSE via
```
streamGenerateContent
```
endpoints

Key endpoints:

/v1beta/models/{model}:generateContent

/v1beta/models/{model}:streamGenerateContent

/v1beta/models/{model}:embedContent

Special: Function calling, grounding with Google Search

基础URL:

https://generativelanguage.googleapis.com

认证: 作为查询参数（
```
?key=
```
）的API密钥或OAuth2
流: 通过
```
streamGenerateContent
```
端点的SSE

关键端点:

/v1beta/models/{model}:generateContent

、

/v1beta/models/{model}:streamGenerateContent

、

/v1beta/models/{model}:embedContent

特殊特性: 函数调用、结合Google搜索的基础能力

Microsoft Graph

Base URL:
```
https://graph.microsoft.com/v1.0
```
(stable),
```
/beta
```
(preview)
Auth: OAuth2 (authorization code or client credentials) via Azure AD

Token URL:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

Key endpoints:
```
/me
```
,
```
/users
```
,
```
/groups
```
,
```
/drives
```
,
```
/sites
```
,
```
/teams
```
Pagination: OData
```
@odata.nextLink
```
Query: OData query params (
```
$select
```
,
```
$filter
```
,
```
$expand
```
,
```
$top
```
,
```
$skip
```
,
```
$orderby
```
)
Official spec: Available in
```
microsoftgraph/msgraph-metadata
```
repo
Batch:
```
POST /$batch
```
with JSON batch requests

基础URL:
```
https://graph.microsoft.com/v1.0
```
（稳定版）、
```
/beta
```
（预览版）
认证: 通过Azure AD的OAuth2（授权码或客户端凭据）

令牌URL:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

关键端点:
```
/me
```
、
```
/users
```
、
```
/groups
```
、
```
/drives
```
、
```
/sites
```
、
```
/teams
```
分页: OData
```
@odata.nextLink
```
查询: OData查询参数（
```
$select
```
、
```
$filter
```
、
```
$expand
```
、
```
$top
```
、
```
$skip
```
、
```
$orderby
```
）
官方规范: 在
```
microsoftgraph/msgraph-metadata
```
仓库中可用
批量:
```
POST /$batch
```
的JSON批量请求

Stripe

Base URL:
```
https://api.stripe.com
```
Auth: Bearer token (secret key) or Basic auth
Content-Type:
```
application/x-www-form-urlencoded
```
(NOT JSON for requests)

Key endpoints:

/v1/customers

/v1/charges

/v1/payment_intents

/v1/subscriptions

/v1/invoices

Versioning: Date-based via
```
Stripe-Version
```
header
Pagination: Cursor-based with
```
starting_after
```
/
```
ending_before
```
Webhooks: Signed with
```
Stripe-Signature
```
header
Idempotency:
```
Idempotency-Key
```
header
Official spec: Available in
```
stripe/openapi
```
repo

基础URL:
```
https://api.stripe.com
```
认证: Bearer令牌（密钥）或Basic认证
Content-Type:
```
application/x-www-form-urlencoded
```
（请求不使用JSON）

关键端点:

/v1/customers

、

/v1/charges

、

/v1/payment_intents

、

/v1/subscriptions

、

/v1/invoices

版本控制: 通过
```
Stripe-Version
```
Header的基于日期的版本控制
分页: 基于
```
starting_after
```
/
```
ending_before
```
的游标分页
Webhooks: 通过
```
Stripe-Signature
```
Header签名
幂等性:
```
Idempotency-Key
```
Header
官方规范: 在
```
stripe/openapi
```
仓库中可用

GitHub REST API

Base URL:
```
https://api.github.com
```
Auth: Bearer token (PAT or OAuth), also supports Basic auth

Key endpoints:

/repos/{owner}/{repo}

/users/{username}

/orgs/{org}

/issues

/pulls

Pagination: Link header with
```
rel="next"
```
,
```
per_page
```
param (max 100)
Rate limits: Via
```
X-RateLimit-*
```
headers
Versioning: API version header
```
X-GitHub-Api-Version: 2022-11-28
```
Official spec: Available in
```
github/rest-api-description
```
repo

基础URL:
```
https://api.github.com
```
认证: Bearer令牌（PAT或OAuth），也支持Basic认证

关键端点:

/repos/{owner}/{repo}

、

/users/{username}

、

/orgs/{org}

、

/issues

、

/pulls

分页: 带有
```
rel="next"
```
的Link Header，
```
per_page
```
参数（最大100）
速率限制: 通过
```
X-RateLimit-*
```
Header
版本控制: API版本Header
```
X-GitHub-Api-Version: 2022-11-28
```
官方规范: 在
```
github/rest-api-description
```
仓库中可用

Slack Web API

Base URL:
```
https://slack.com/api
```
Auth: Bearer token (Bot or User token)

Content-Type: Mix of

application/x-www-form-urlencoded

and

application/json

Key endpoints:

/chat.postMessage

/conversations.list

/users.list

/files.upload

Pagination: Cursor-based with
```
cursor
```
and
```
next_cursor
```
Rate limits: Tier-based (1-4),
```
Retry-After
```
header

基础URL:
```
https://slack.com/api
```
认证: Bearer令牌（Bot或用户令牌）

Content-Type:

application/x-www-form-urlencoded

与

application/json

混合使用

关键端点:

/chat.postMessage

、

/conversations.list

、

/users.list

、

/files.upload

分页: 基于
```
cursor
```
和
```
next_cursor
```
的游标分页
速率限制: 基于层级（1-4），
```
Retry-After
```
Header

AWS APIs (General Pattern)

AWS APIs（通用模式）

Auth: AWS Signature V4 (
```
Authorization
```
header)
Endpoints: Regional (
```
{service}.{region}.amazonaws.com
```
)
Key services: S3, Lambda, DynamoDB, SES, SNS, SQS, Bedrock
Special: Many AWS APIs use custom protocols (JSON RPC, Query, REST-XML)
Official specs: AWS publishes Smithy models, some have OpenAPI exports

认证: AWS Signature V4（
```
Authorization
```
Header）
端点: 区域化（
```
{service}.{region}.amazonaws.com
```
）
关键服务: S3、Lambda、DynamoDB、SES、SNS、SQS、Bedrock
特殊特性: 许多AWS API使用自定义协议（JSON RPC、Query、REST-XML）
官方规范: AWS发布Smithy模型，部分有OpenAPI导出版本

Cloudflare

Base URL:
```
https://api.cloudflare.com/client/v4
```
Auth: Bearer token or
```
X-Auth-Email
```
+
```
X-Auth-Key
```
headers
Key endpoints:
```
/zones
```
,
```
/dns_records
```
,
```
/workers
```
,
```
/accounts
```
Pagination: Page-based with
```
page
```
and
```
per_page
```
Response envelope:
```
{ success, errors, messages, result }
```

基础URL:
```
https://api.cloudflare.com/client/v4
```
认证: Bearer令牌或
```
X-Auth-Email
```
+
```
X-Auth-Key
```
Headers
关键端点:
```
/zones
```
、
```
/dns_records
```
、
```
/workers
```
、
```
/accounts
```
分页: 基于
```
page
```
和
```
per_page
```
的分页
响应信封:
```
{ success, errors, messages, result }
```

Vercel

Base URL:
```
https://api.vercel.com
```
Auth: Bearer token

Key endpoints:

/v9/projects

/v6/deployments

/v1/domains

/v1/teams

Pagination: Varies by endpoint (cursor or offset)

基础URL:
```
https://api.vercel.com
```
认证: Bearer令牌

关键端点:

/v9/projects

、

/v6/deployments

、

/v1/domains

、

/v1/teams

分页: 因端点而异（游标或偏移量）

Twilio

Base URL:
```
https://api.twilio.com/2010-04-01
```
Auth: Basic auth (Account SID:Auth Token)
Content-Type:
```
application/x-www-form-urlencoded
```
(requests)

Key endpoints:

/Accounts/{sid}/Messages

/Accounts/{sid}/Calls

Pagination: Page-based with
```
PageSize
```
and
```
PageToken
```

基础URL:
```
https://api.twilio.com/2010-04-01
```
认证: Basic认证（Account SID:Auth Token）
Content-Type:
```
application/x-www-form-urlencoded
```
（请求）

关键端点:

/Accounts/{sid}/Messages

、

/Accounts/{sid}/Calls

分页: 基于
```
PageSize
```
和
```
PageToken
```
的分页

SendGrid

Base URL:
```
https://api.sendgrid.com/v3
```
Auth: Bearer token
Key endpoints:
```
/mail/send
```
,
```
/marketing/contacts
```
,
```
/templates
```

基础URL:
```
https://api.sendgrid.com/v3
```
认证: Bearer令牌
关键端点:
```
/mail/send
```
、
```
/marketing/contacts
```
、
```
/templates
```

Multi-File Organization

多文件组织

For large API specs (50+ endpoints), split into multiple files:

specs/
├── {provider}/
│   ├── openapi.yaml           # Entry document
│   ├── paths/
│   │   ├── {resource}.yaml    # Per-resource paths
│   │   └── ...
│   ├── components/
│   │   ├── schemas/
│   │   │   ├── {Model}.yaml
│   │   │   └── ...
│   │   ├── parameters/
│   │   │   └── common.yaml
│   │   ├── responses/
│   │   │   └── errors.yaml
│   │   └── securitySchemes/
│   │       └── auth.yaml
│   └── README.md              # Provider-specific notes

Use

$ref

for cross-file references:

yaml

paths:
  /users:
    $ref: './paths/users.yaml#/~1users'

components:
  schemas:
    User:
      $ref: './components/schemas/User.yaml'

对于大型API规范（50+端点），拆分为多个文件：

specs/
├── {provider}/
│   ├── openapi.yaml           # 入口文档
│   ├── paths/
│   │   ├── {resource}.yaml    # 每个资源对应一个路径文件
│   │   └── ...
│   ├── components/
│   │   ├── schemas/
│   │   │   ├── {Model}.yaml
│   │   │   └── ...
│   │   ├── parameters/
│   │   │   └── common.yaml
│   │   ├── responses/
│   │   │   └── errors.yaml
│   │   └── securitySchemes/
│   │       └── auth.yaml
│   └── README.md              # 提供商特定说明

使用

$ref

进行跨文件引用：

yaml

paths:
  /users:
    $ref: './paths/users.yaml#/~1users'

components:
  schemas:
    User:
      $ref: './components/schemas/User.yaml'

Validation Rules

验证规则

After generating a spec, verify these rules:

生成规范后，验证以下规则：

MUST (Errors)

必须遵守（错误项）

```
openapi
```
field is exactly
```
3.2.0
```
```
info.title
```
and
```
info.version
```
are present
At least one of
```
paths
```
,
```
components
```
, or
```
webhooks
```
is present
Every
```
$ref
```
points to a valid target
Every
```
operationId
```
is unique across the spec
All required
```
schema
```
properties are listed in the
```
required
```
array
Path parameters in the URL template have matching parameter definitions
Security schemes referenced in
```
security
```
arrays are defined in
```
components/securitySchemes
```
HTTP methods are lowercase (
```
get
```
,
```
post
```
,
```
put
```
,
```
patch
```
,
```
delete
```
)
Response status codes are strings (
```
'200'
```
, not
```
200
```
)

```
openapi
```
字段必须精确为
```
3.2.0
```
```
info.title
```
和
```
info.version
```
必须存在
至少存在
```
paths
```
、
```
components
```
或
```
webhooks
```
中的一个
每个
```
$ref
```
指向有效的目标
每个
```
operationId
```
在规范中唯一
所有必填的
```
schema
```
属性都列在
```
required
```
数组中
URL模板中的路径参数有匹配的参数定义
```
security
```
数组中引用的安全方案在
```
components/securitySchemes
```
中定义
HTTP方法为小写（
```
get
```
、
```
post
```
、
```
put
```
、
```
patch
```
、
```
delete
```
）
响应状态码为字符串（如
```
'200'
```
，而非
```
200
```
）

SHOULD (Warnings)

建议遵守（警告项）

Every operation has an
```
operationId
```
(needed for SDK generation)
Every operation has a
```
summary
```
or
```
description
```
Every operation has at least one response defined
Schemas use
```
$ref
```
for reuse when a type appears 2+ times
Error responses (4xx, 5xx) include response body schemas
Pagination endpoints document pagination parameters
Rate-limited endpoints document rate limit headers

Streaming endpoints use

text/event-stream

application/x-ndjson

media types with

itemSchema

Tags are used to group related operations
```
examples
```
are provided for complex request/response bodies

每个操作都有
```
operationId
```
（SDK生成所需）
每个操作都有
```
summary
```
或
```
description
```
每个操作至少定义一个响应
当某类型出现2次以上时，使用
```
$ref
```
复用
错误响应（4xx、5xx）包含响应体schema
分页端点记录分页参数
有限速的端点记录限速Header

流端点使用

text/event-stream

或

application/x-ndjson

媒体类型并搭配

itemSchema

使用标签对相关操作进行分组
为复杂的请求/响应体提供
```
examples
```

RECOMMENDED (Best Practices)

Generation Workflow

生成工作流

When the user requests a spec, follow this exact workflow:

Check for official spec: Try to fetch the provider's official OpenAPI spec first
If official spec exists: Upgrade it to OAS 3.2.0, clean up, add missing features (streaming, structured tags)
If no official spec: Fetch the provider's API documentation via WebFetch
Extract endpoints: Identify all endpoints, methods, parameters, request/response bodies
Map auth: Determine authentication method(s) and create security schemes
Generate spec: Build the YAML following the structure above
Add streaming: If the API supports streaming (especially AI APIs), use OAS 3.2 streaming patterns
Validate: Check against the validation rules
Write file: Save to
```
specs/{provider}/openapi.yaml
```
(or user-specified path)
Report: Summarize what was generated (endpoint count, schemas, auth methods)

当用户请求规范时，严格遵循以下工作流：

检查官方规范：首先尝试获取提供商的官方OpenAPI规范
若存在官方规范：将其升级到OAS 3.2.0，清理并添加缺失特性（流、结构化标签）
若无官方规范：通过WebFetch获取提供商的API文档
提取端点：识别所有端点、方法、参数、请求/响应体
映射认证：确定认证方式并创建安全方案
生成规范：按照上述结构构建YAML
添加流支持：若API支持流（尤其是AI API），使用OAS 3.2流模式
验证：根据验证规则检查
写入文件：保存到
```
specs/{provider}/openapi.yaml
```
（或用户指定路径）
报告：总结生成内容（端点数量、schema数量、认证方式）

Example: Generating a Minimal OpenAI Spec

示例：生成最小化OpenAI规范

yaml

openapi: 3.2.0

info:
  title: OpenAI API
  version: "2.3.0"
  description: |
    OpenAPI 3.2.0 specification for the OpenAI API.
    Covers Chat Completions, Embeddings, and Models endpoints.

    Source: https://platform.openai.com/docs/api-reference
  contact:
    name: OpenAI Support
    url: https://help.openai.com
  license:
    name: MIT
    identifier: MIT
  x-generated-by: "OAS API Spec Generator Skill"

servers:
  - url: https://api.openai.com
    description: Production

security:
  - bearerAuth: []

tags:
  - name: Chat
    summary: Chat completions
    kind: resource
  - name: Embeddings
    summary: Text embeddings
    kind: resource
  - name: Models
    summary: Model management
    kind: resource

paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a chat completion
      tags: [Chat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: Basic chat request
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content: "Hello!"
              streaming:
                summary: Streaming request
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content: "Hello!"
                  stream: true
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
              itemSchema:
                $ref: '#/components/schemas/ChatCompletionChunk'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/embeddings:
    post:
      operationId: createEmbedding
      summary: Create embeddings
      tags: [Embeddings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: Embedding response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'

  /v1/models:
    get:
      operationId: listModels
      summary: List available models
      tags: [Models]
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'

  /v1/models/{model_id}:
    get:
      operationId: getModel
      summary: Retrieve a model
      tags: [Models]
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the model (e.g., gpt-4o)
      responses:
        '200':
          description: Model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'

components:
  schemas:
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          description: Model ID (e.g., gpt-4o, gpt-4o-mini)
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
        max_tokens:
          type: integer
          nullable: true
        stream:
          type: boolean
          default: false
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          oneOf:
            - type: string
              enum: [none, auto, required]
            - $ref: '#/components/schemas/ToolChoice'

    ChatMessage:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
        name:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string

    ContentPart:
      oneOf:
        - type: object
          required: [type, text]
          properties:
            type:
              type: string
              const: text
            text:
              type: string
        - type: object
          required: [type, image_url]
          properties:
            type:
              type: string
              const: image_url
            image_url:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                detail:
                  type: string
                  enum: [auto, low, high]

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                enum: [stop, length, tool_calls, content_filter]
        usage:
          $ref: '#/components/schemas/Usage'

    ChatCompletionChunk:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              delta:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                    nullable: true
                  tool_calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/ToolCallDelta'
              finish_reason:
                type: string
                nullable: true
                enum: [stop, length, tool_calls, content_filter]

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

    Tool:
      type: object
      required: [type, function]
      properties:
        type:
          type: string
          const: function
        function:
          type: object
          required: [name]
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object

    ToolChoice:
      type: object
      required: [type, function]
      properties:
        type:
          type: string
          const: function
        function:
          type: object
          required: [name]
          properties:
            name:
              type: string

    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          const: function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string

    ToolCallDelta:
      type: object
      properties:
        index:
          type: integer
        id:
          type: string
        type:
          type: string
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string

    EmbeddingRequest:
      type: object
      required: [model, input]
      properties:
        model:
          type: string
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        encoding_format:
          type: string
          enum: [float, base64]
          default: float
        dimensions:
          type: integer

    EmbeddingResponse:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            type: object
            properties:
              object:
                type: string
                const: embedding
              index:
                type: integer
              embedding:
                type: array
                items:
                  type: number
        model:
          type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            total_tokens:
              type: integer

    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: model
        created:
          type: integer
        owned_by:
          type: string

    ModelList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'

    APIError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [message, type]
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              type: string
              nullable: true

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    RateLimited:
      description: Rate limit exceeded
      headers:
        retry-after:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        OpenAI API key as Bearer token.
        Get your key at: https://platform.openai.com/api-keys

externalDocs:
  description: OpenAI API Reference
  url: https://platform.openai.com/docs/api-reference

yaml

openapi: 3.2.0

info:
  title: OpenAI API
  version: "2.3.0"
  description: |
    OpenAPI 3.2.0 specification for the OpenAI API.
    Covers Chat Completions, Embeddings, and Models endpoints.

    Source: https://platform.openai.com/docs/api-reference
  contact:
    name: OpenAI Support
    url: https://help.openai.com
  license:
    name: MIT
    identifier: MIT
  x-generated-by: "OAS API Spec Generator Skill"

servers:
  - url: https://api.openai.com
    description: Production

security:
  - bearerAuth: []

tags:
  - name: Chat
    summary: Chat completions
    kind: resource
  - name: Embeddings
    summary: Text embeddings
    kind: resource
  - name: Models
    summary: Model management
    kind: resource

paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a chat completion
      tags: [Chat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: Basic chat request
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content: "Hello!"
              streaming:
                summary: Streaming request
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content: "Hello!"
                  stream: true
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
              itemSchema:
                $ref: '#/components/schemas/ChatCompletionChunk'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/embeddings:
    post:
      operationId: createEmbedding
      summary: Create embeddings
      tags: [Embeddings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: Embedding response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'

  /v1/models:
    get:
      operationId: listModels
      summary: List available models
      tags: [Models]
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'

  /v1/models/{model_id}:
    get:
      operationId: getModel
      summary: Retrieve a model
      tags: [Models]
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the model (e.g., gpt-4o)
      responses:
        '200':
          description: Model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'

components:
  schemas:
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          description: Model ID (e.g., gpt-4o, gpt-4o-mini)
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
        max_tokens:
          type: integer
          nullable: true
        stream:
          type: boolean
          default: false
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          oneOf:
            - type: string
              enum: [none, auto, required]
            - $ref: '#/components/schemas/ToolChoice'

    ChatMessage:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
        name:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string

    ContentPart:
      oneOf:
        - type: object
          required: [type, text]
          properties:
            type:
              type: string
              const: text
            text:
              type: string
        - type: object
          required: [type, image_url]
          properties:
            type:
              type: string
              const: image_url
            image_url:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                detail:
                  type: string
                  enum: [auto, low, high]

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                enum: [stop, length, tool_calls, content_filter]
        usage:
          $ref: '#/components/schemas/Usage'

    ChatCompletionChunk:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              delta:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                    nullable: true
                  tool_calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/ToolCallDelta'
              finish_reason:
                type: string
                nullable: true
                enum: [stop, length, tool_calls, content_filter]

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

    Tool:
      type: object
      required: [type, function]
      properties:
        type:
          type: string
          const: function
        function:
          type: object
          required: [name]
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object

    ToolChoice:
      type: object
      required: [type, function]
      properties:
        type:
          type: string
          const: function
        function:
          type: object
          required: [name]
          properties:
            name:
              type: string

    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          const: function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string

    ToolCallDelta:
      type: object
      properties:
        index:
          type: integer
        id:
          type: string
        type:
          type: string
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string

    EmbeddingRequest:
      type: object
      required: [model, input]
      properties:
        model:
          type: string
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        encoding_format:
          type: string
          enum: [float, base64]
          default: float
        dimensions:
          type: integer

    EmbeddingResponse:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            type: object
            properties:
              object:
                type: string
                const: embedding
              index:
                type: integer
              embedding:
                type: array
                items:
                  type: number
        model:
          type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            total_tokens:
              type: integer

    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: model
        created:
          type: integer
        owned_by:
          type: string

    ModelList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'

    APIError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [message, type]
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              type: string
              nullable: true

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    RateLimited:
      description: Rate limit exceeded
      headers:
        retry-after:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        作为Bearer令牌的OpenAI API密钥。
        获取地址：https://platform.openai.com/api-keys

externalDocs:
  description: OpenAI API Reference
  url: https://platform.openai.com/docs/api-reference

Output Format

输出格式

Always generate specs as YAML files (not JSON). YAML is more readable and is the standard format for OpenAPI specs.

When the user requests a spec:

Ask which endpoints/services they need (or generate all)
Generate the full YAML spec
Save it to the filesystem at a sensible path
Provide a summary of what was generated

Summary format:

Generated OAS 3.2.0 spec for {Provider} API:
- Endpoints: {count}
- Schemas: {count}
- Auth: {method(s)}
- Streaming: {yes/no}
- File: {path}

始终以YAML文件（而非JSON）生成规范。YAML更具可读性，是OpenAPI规范的标准格式。

当用户请求规范时：

询问用户需要哪些端点/服务(或生成全部)
生成完整的YAML规范
将其保存到文件系统的合理路径
提供生成内容的摘要

摘要格式：

为{Provider} API生成OAS 3.2.0规范：
- 端点数量：{count}
- Schema数量：{count}
- 认证方式：{method(s)}
- 流支持：{是/否}
- 文件路径：{path}