oas-api-spec-generator

Original：🇺🇸 English

Translated

Generate OpenAPI 3.2.0 specifications for third-party APIs (OpenAI, Anthropic, Google, Microsoft, Stripe, GitHub, Slack, AWS, and more)

1installs

Sourcedeepparser/oas-api-spec-generator

Added on2026-02-24

NPX Install

npx skill4agent add deepparser/oas-api-spec-generator oas-api-spec-generator

SKILL.md Content

View Translation Comparison →

OAS Third-Party API Spec Generator

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

When to Use This 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"

How This Skill Works

Step 1: Identify the Target 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)

Step 2: Fetch Current API Documentation

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.

Step 3: Generate the OAS 3.2.0 Spec

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

Step 4: Validate

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

OAS 3.2.0 Spec Structure

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}"

Provider-Specific Auth Patterns

Bearer Token (API Key as Bearer)

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: []

Custom Header API Key

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}

OAuth 2.0 Authorization Code

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"

OAuth 2.0 Client Credentials

Used by: Microsoft Graph (app-only), 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"

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"

# Per-operation security can combine:
# security:
#   - apiKey: []
#     orgHeader: []

Streaming Support (OAS 3.2.0)

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

Server-Sent Events (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"

JSON Lines / NDJSON Streaming

Used by: Some batch/export APIs

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

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'

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

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

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

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

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

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

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

AWS APIs (General Pattern)

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

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 }
```

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)

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
```

SendGrid

Base URL:
```
https://api.sendgrid.com/v3
```
Auth: Bearer token
Key endpoints:
```
/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'

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
```
)

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

RECOMMENDED (Best Practices)

Use

operationId

naming:

{verb}{Resource}

(e.g.,

createUser

listOrders

)

Group related endpoints under the same tag
Use structured tags with
```
kind
```
and
```
parent
```
(OAS 3.2)
Document all authentication methods the provider supports
Include
```
externalDocs
```
linking to the provider's official documentation

Add

x-generated-by

and

x-source-documentation

info

For AI APIs: document token limits, model availability, and pricing tiers in descriptions

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)

Example: Generating a Minimal OpenAI Spec

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

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}

OAS Third-Party API Spec Generator

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

When to Use This 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"

How This Skill Works

Step 1: Identify the Target 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)

Step 2: Fetch Current API Documentation

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.

Step 3: Generate the OAS 3.2.0 Spec

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

Step 4: Validate

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

OAS 3.2.0 Spec Structure

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}"

Provider-Specific Auth Patterns

Bearer Token (API Key as Bearer)

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: []

Custom Header API Key

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}

OAuth 2.0 Authorization Code

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"

OAuth 2.0 Client Credentials

Used by: Microsoft Graph (app-only), 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"

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"

# Per-operation security can combine:
# security:
#   - apiKey: []
#     orgHeader: []

Streaming Support (OAS 3.2.0)

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

Server-Sent Events (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"

JSON Lines / NDJSON Streaming

Used by: Some batch/export APIs

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

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'

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

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

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

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

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

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

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

AWS APIs (General Pattern)

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

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 }
```

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)

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
```

SendGrid

Base URL:
```
https://api.sendgrid.com/v3
```
Auth: Bearer token
Key endpoints:
```
/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'

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
```
)

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

RECOMMENDED (Best Practices)

Use

operationId

naming:

{verb}{Resource}

(e.g.,

createUser

listOrders

)

Group related endpoints under the same tag
Use structured tags with
```
kind
```
and
```
parent
```
(OAS 3.2)
Document all authentication methods the provider supports
Include
```
externalDocs
```
linking to the provider's official documentation

Add

x-generated-by

and

x-source-documentation

info

For AI APIs: document token limits, model availability, and pricing tiers in descriptions

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)

Example: Generating a Minimal OpenAI Spec

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

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}

oas-api-spec-generator

NPX Install

Tags

SKILL.md Content

OAS Third-Party API Spec Generator

When to Use This Skill

How This Skill Works

Step 1: Identify the Target API

Step 2: Fetch Current API Documentation

Step 3: Generate the OAS 3.2.0 Spec

Step 4: Validate

OAS 3.2.0 Spec Structure

Provider-Specific Auth Patterns

Bearer Token (API Key as Bearer)

Custom Header API Key

OAuth 2.0 Authorization Code

OAuth 2.0 Client Credentials

AWS Signature V4

Multi-Auth (Provider + Org)

Streaming Support (OAS 3.2.0)

Server-Sent Events (SSE)

JSON Lines / NDJSON Streaming

Common Response Patterns

Paginated List Response

Standard Error Response

Provider Quick-Reference

OpenAI API

Anthropic API

Google AI (Gemini)

Microsoft Graph

Stripe

GitHub REST API

Slack Web API

AWS APIs (General Pattern)

Cloudflare

Vercel

Twilio

SendGrid

Multi-File Organization

Validation Rules

MUST (Errors)

SHOULD (Warnings)

RECOMMENDED (Best Practices)

Generation Workflow

Example: Generating a Minimal OpenAI Spec

Output Format

oas-api-spec-generator

NPX Install

Tags

SKILL.md Content

OAS Third-Party API Spec Generator

When to Use This Skill

How This Skill Works

Step 1: Identify the Target API

Step 2: Fetch Current API Documentation

Step 3: Generate the OAS 3.2.0 Spec

Step 4: Validate

OAS 3.2.0 Spec Structure

Provider-Specific Auth Patterns

Bearer Token (API Key as Bearer)

Custom Header API Key

OAuth 2.0 Authorization Code

OAuth 2.0 Client Credentials

AWS Signature V4

Multi-Auth (Provider + Org)

Streaming Support (OAS 3.2.0)

Server-Sent Events (SSE)

JSON Lines / NDJSON Streaming

Common Response Patterns

Paginated List Response

Standard Error Response

Provider Quick-Reference

OpenAI API

Anthropic API

Google AI (Gemini)

Microsoft Graph

Stripe

GitHub REST API

Slack Web API

AWS APIs (General Pattern)