speakeasy-api/agent-skills/writing-openapi-specs

Name: writing-openapi-specs
Author: speakeasy-api

Claude Code and agent skill by speakeasy-api/agent-skills

Trust tier 2

community

LLM review pending

Source check pending

Checking that the SKILL.md file is still in the repository.

Reference guide for OpenAPI specification best practices, naming conventions, and expressing complex REST API patterns like polymorphism, enums, file uploads, and server-sent events. Use when writing or improving OpenAPI specs to ensure they follow established conventions and generate quality SDKs.

Install

npx vskill@latest install speakeasy-api/agent-skills/writing-openapi-specs

SKILL.md

Writing OpenAPI Specs

Reference for OpenAPI best practices and conventions. This skill provides guidance on taste, conventions, and grey areas not covered by the OpenAPI specification itself.

When to Use This Skill

Writing a new OpenAPI specification
Improving operation naming and organization
Expressing complex data types (enums, polymorphism, nullable)
Handling file uploads, streaming, or server-sent events
Making specs more code-gen friendly
Understanding reusability patterns (components vs inline)

Core Principles

Naming Conventions

Operation IDs: Use lowercase with underscores, following resource_action pattern:

yaml

# Good
operationId: users_list
operationId: users_get
operationId: users_create
 
# Avoid
operationId: GetApiV1Users    # Auto-generated, not semantic

Component Names: Use PascalCase for schemas, parameters, and other reusable components:

yaml

components:
  schemas:
    UserProfile:      # PascalCase
    OrderHistory:     # PascalCase
  parameters:
    PageLimit:        # PascalCase

Tags: Use lowercase with hyphens for machine-friendly tags:

yaml

tags:
  - name: user-management
    description: Operations for managing users
  - name: order-processing
    description: Operations for processing orders

For more details, see reference/operations.md and reference/components.md.

Documentation Standards

Use CommonMark: All description fields support CommonMark syntax for rich formatting:

yaml

description: |
  Retrieves a user by ID.
 
  ## Authorization
  Requires `users:read` scope.
 
  ## Rate Limits
  - 100 requests per minute per API key
  - 1000 requests per hour per IP

Be Specific: Provide actionable information, not generic descriptions:

yaml

# Good
description: Returns a paginated list of active users, ordered by creation date (newest first)
 
# Avoid
description: Gets users

Use `examples` over `example`: The plural examples field provides better SDK generation:

yaml

# Good
examples:
  basic_user:
    value:
      id: 123
      name: "John Doe"
  admin_user:
    value:
      id: 456
      name: "Jane Admin"
      role: admin
 
# Avoid single example
example:
  id: 123
  name: "John Doe"

For more details, see reference/examples.md.

Reusability

Create components for:

Schemas used in multiple operations
Common parameters (pagination, filtering)
Common responses (errors, success patterns)
Security schemes

Keep inline for:

Operation-specific request bodies
Unique response shapes
One-off parameters

yaml

# Reusable schema
components:
  schemas:
    User:
      type: object
      properties:
        id: {type: integer}
        name: {type: string}
 
# Reference it
paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

For more details, see reference/components.md.

Complex Patterns Quick Reference

These patterns are commonly challenging. Brief examples below with links to detailed guidance.

Enums

Use string enums with clear, semantic values:

yaml

type: string
enum:
  - pending
  - approved
  - rejected
  - cancelled

Avoid:

Numeric strings ("0", "1", "2")
Generic values ("value1", "value2")
Unclear abbreviations ("pnd", "appr")

See reference/schemas.md#enums for more.

Polymorphism (oneOf/allOf/anyOf)

oneOf: Value matches exactly one schema (type discrimination)

yaml

PaymentMethod:
  oneOf:
    - $ref: '#/components/schemas/CreditCard'
    - $ref: '#/components/schemas/BankAccount'
    - $ref: '#/components/schemas/PayPal'
  discriminator:
    propertyName: type
    mapping:
      credit_card: '#/components/schemas/CreditCard'
      bank_account: '#/components/schemas/BankAccount'
      paypal: '#/components/schemas/PayPal'

allOf: Value matches all schemas (composition/inheritance)

yaml

AdminUser:
  allOf:
    - $ref: '#/components/schemas/User'
    - type: object
      properties:
        permissions:
          type: array
          items: {type: string}

anyOf: Value matches one or more schemas (flexible union)

yaml

SearchFilter:
  anyOf:
    - $ref: '#/components/schemas/TextFilter'
    - $ref: '#/components/schemas/DateFilter'
    - $ref: '#/components/schemas/NumericFilter'

See reference/schemas.md#polymorphism for detailed guidance.

Discriminators

Use discriminators with oneOf for efficient type identification:

yaml

Pet:
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      cat: '#/components/schemas/Cat'
 
Dog:
  type: object
  required: [petType, bark]
  properties:
    petType:
      type: string
      enum: [dog]
    bark:
      type: string
 
Cat:
  type: object
  required: [petType, meow]
  properties:
    petType:
      type: string
      enum: [cat]
    meow:
      type: string

See reference/schemas.md#discriminators for more.

Nullable Types

Handle null values differently based on OpenAPI version:

OpenAPI 3.1 (JSON Schema 2020-12 compliant):

yaml

type: [string, "null"]
# or
type: string
nullable: true  # Still supported for compatibility

OpenAPI 3.0:

yaml

type: string
nullable: true

For optional fields, use required array:

yaml

type: object
properties:
  name: {type: string}      # Can be omitted
  email: {type: string}     # Can be omitted
required: [name]            # email is optional

See reference/schemas.md#nullable for more.

File Uploads

Use multipart/form-data for file uploads:

yaml

requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          file:
            type: string
            format: binary
          metadata:
            type: object
            properties:
              description: {type: string}
              tags:
                type: array
                items: {type: string}
        required: [file]

For base64-encoded files in JSON:

yaml

requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          filename: {type: string}
          content:
            type: string
            format: byte  # base64-encoded

See reference/request-bodies.md#file-uploads for more.

Server-Sent Events (SSE)

Express streaming responses with text/event-stream:

yaml

responses:
  '200':
    description: Stream of events
    content:
      text/event-stream:
        schema:
          type: string
          description: |
            Server-sent events stream. Each event follows the format:
 
            ```
            event: message
            data: {"type": "update", "content": "..."}
 
            ```
        examples:
          notification_stream:
            value: |
              event: message
              data: {"type": "notification", "message": "New order received"}
 
              event: message
              data: {"type": "notification", "message": "Order processing complete"}

See reference/responses.md#streaming for more patterns.

Field Reference

Detailed guidance for each major OpenAPI field:

Operations: Operation IDs, methods, tags, deprecation → reference/operations.md
Schemas: Data types, polymorphism, enums, nullable → reference/schemas.md
Parameters: Path, query, header, cookie parameters → reference/parameters.md
Request Bodies: Content types, file uploads, encoding → reference/request-bodies.md
Responses: Status codes, streaming, error patterns → reference/responses.md
Components: Reusable definitions, organization → reference/components.md
Security: Authentication schemes, scopes, granular control → reference/security.md
Examples: Single and multiple examples, placement → reference/examples.md

SDK Generation Considerations

When writing specs for SDK generation:

Always define `operationId`: Required for meaningful method names
Provide rich examples: Helps generate better documentation and tests
Be explicit about required fields: Affects SDK method signatures
Use discriminators with oneOf: Generates type-safe unions
Document error responses: Generates better error handling code

Example SDK-friendly operation:

yaml

paths:
  /users:
    get:
      operationId: users_list
      summary: List all users
      description: Returns a paginated list of users
      parameters:
        - name: limit
          in: query
          schema: {type: integer, default: 20}
        - name: offset
          in: query
          schema: {type: integer, default: 0}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required: [data, pagination]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
              examples:
                success:
                  value:
                    data: [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}]
                    pagination: {total: 100, limit: 20, offset: 0}

This generates: sdk.users.list({limit: 20, offset: 0})

Common Pitfalls

Don't:

Use generic descriptions like "Gets data" or "Returns object"
Mix naming conventions (pick one style and stick to it)
Forget operationId (causes auto-generated names)
Use example when you mean examples (plural is better)
Make everything required (be thoughtful about optional fields)
Inline everything (use components for reusability)
Reference everything (inline simple one-off schemas)
Forget to document error responses
Use magic numbers without explanation
Omit content types (be explicit)

Do:

Provide actionable, specific descriptions
Use consistent naming patterns throughout
Define clear operationId for every operation
Use examples (plural) with named examples
Carefully consider required vs optional fields
Balance reusability with clarity
Document all expected responses (success and errors)
Explain constraints and validation rules
Be explicit about content types and formats

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/writing-openapi-specs/SKILL.md

Popularity

Repository stars: 6
Repository forks: 4
7-day trend score: 10

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 24 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/speakeasy-api/agent-skills/writing-openapi-specs/badge)](https://verified-skill.com/skills/speakeasy-api/agent-skills/writing-openapi-specs)

Something wrong with this skill or its page? Tell us.