Openapi Specification

OpenAPI Specification

Design, validate, and maintain OpenAPI 3.x specifications for REST API contracts. Covers schema patterns, security schemes, versioning, and code generation integration.

When to Use This Skill

• Creating a new OpenAPI specification from scratch
• Adding endpoints or schemas to an existing spec
• Reviewing or validating an API contract for correctness
• Setting up code generation from OpenAPI definitions
• Designing reusable schema components for large APIs
• Implementing security schemes in API specifications
• Managing API versioning and deprecation

Quick Reference

---

Workflow

Phase 1: Design       → Define API overview, resources, and operations
Phase 2: Schema       → Build data models with reusable components
Phase 3: Validate     → Lint and verify the spec for correctness
Phase 4: Integrate    → Generate docs, SDKs, and contract tests

---

Phase 1: API Design

Start with a high-level design before writing the spec:

1. Identify resources -- what nouns does this API expose? 2. Map operations -- what CRUD and custom actions apply to each resource? 3. Define relationships -- how do resources reference each other? 4. Plan authentication -- what security schemes are needed? 5. Set conventions -- naming style, pagination, error format

Spec Skeleton

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [What this API does]
paths:
  /resources:
    get:
      summary: List resources
      operationId: listResources
    post:
      summary: Create a resource
      operationId: createResource
  /resources/{id}:
    get:
      summary: Get a resource
      operationId: getResource
components:
  schemas: {}
  securitySchemes: {}

---

Phase 2: Schema Design

Build data models using components/schemas for reuse:

• Use $ref to reference shared schemas -- never duplicate definitions
• Apply allOf for composition, oneOf / anyOf for polymorphism
• Add example values to every schema and property
• Use required arrays explicitly -- don't rely on implicit behavior
• Document nullable fields with type: [string, "null"] (3.1) or nullable: true (3.0)

---

Phase 3: Validate

Run validation before committing any spec changes:

# Spectral (recommended)
spectral lint openapi.yaml

# Redocly
redocly lint openapi.yaml

# swagger-cli
swagger-cli validate openapi.yaml

Common Validation Issues

---

Phase 4: Integrate

Use the validated spec to generate downstream artifacts:

• Documentation: Redoc, Swagger UI, Stoplight
• Client SDKs: openapi-generator, autorest, orval
• Server stubs: openapi-generator with server templates
• Contract tests: Schemathesis, Dredd, Prism

---

Quality Checklist

• [ ] All paths have operationIds
• [ ] HTTP methods match resource actions (GET reads, POST creates, etc.)
• [ ] Every response has a description and schema
• [ ] Security requirements defined at operation or global level
• [ ] Examples provided for request and response bodies
• [ ] Consistent naming conventions (camelCase, snake_case -- pick one)
• [ ] Deprecation fields set on sunset endpoints
• [ ] Spec passes linter with zero errors

---

Anti-Patterns

• Do not inline schemas -- use $ref to components/schemas for anything reused
• Do not mix API versions in a single spec file
• Do not use 200 OK for create operations -- use 201 Created
• Do not omit error response schemas -- document 4xx and 5xx consistently
• Do not use additionalProperties: true without clear justification

OpenAPI Specification Patterns Reference

Patterns, conventions, and techniques for designing robust OpenAPI 3.x specifications.

OpenAPI 3.x Structure

Top-Level Organization

openapi: 3.1.0          # Specification version

info:                    # API metadata
  title: My API
  version: 1.0.0
  description: ...
  contact: ...
  license: ...

servers:                 # Base URLs
  - url: https://api.example.com/v1
    description: Production

paths:                   # Endpoints and operations
  /resources: ...

components:              # Reusable definitions
  schemas: ...
  parameters: ...
  responses: ...
  securitySchemes: ...
  requestBodies: ...
  headers: ...

security:                # Global security requirements
  - bearerAuth: []

tags:                    # Logical grouping of operations
  - name: resources
    description: Resource management

Path and Operation Structure

paths:
  /resources/{id}:
    parameters:                    # Path-level parameters (shared by all operations)
      - $ref: '#/components/parameters/ResourceId'
    get:
      tags: [resources]
      summary: Get a resource         # Short (< 120 chars)
      description: |                   # Detailed explanation
        Returns a single resource by its unique identifier.
      operationId: getResource         # Unique, used for codegen
      parameters:                      # Operation-specific params
        - $ref: '#/components/parameters/IncludeDeleted'
      responses:
        '200':
          description: Resource found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
              example:
                id: abc-123
                name: Example
        '404':
          $ref: '#/components/responses/NotFound'

---

Schema Design Patterns

Composition with allOf

Use allOf to compose schemas from shared building blocks:

schemas:
  BaseResource:
    type: object
    properties:
      id:
        type: string
        format: uuid
      createdAt:
        type: string
        format: date-time
      updatedAt:
        type: string
        format: date-time

  User:
    allOf:
      - $ref: '#/components/schemas/BaseResource'
      - type: object
        required: [email, name]
        properties:
          email:
            type: string
            format: email
          name:
            type: string

Polymorphism with oneOf and Discriminators

Use oneOf with discriminator for type unions:

schemas:
  Notification:
    oneOf:
      - $ref: '#/components/schemas/EmailNotification'
      - $ref: '#/components/schemas/SmsNotification'
      - $ref: '#/components/schemas/PushNotification'
    discriminator:
      propertyName: type
      mapping:
        email: '#/components/schemas/EmailNotification'
        sms: '#/components/schemas/SmsNotification'
        push: '#/components/schemas/PushNotification'

  EmailNotification:
    type: object
    required: [type, to, subject]
    properties:
      type:
        type: string
        enum: [email]
      to:
        type: string
        format: email
      subject:
        type: string

Read vs Write Schemas

Separate schemas for create/update vs read operations:

schemas:
  UserCreate:
    type: object
    required: [email, name]
    properties:
      email:
        type: string
        format: email
      name:
        type: string

  UserResponse:
    allOf:
      - $ref: '#/components/schemas/BaseResource'
      - $ref: '#/components/schemas/UserCreate'

This avoids clients sending id, createdAt, or other server-managed fields.

Pagination Pattern

schemas:
  PaginatedResponse:
    type: object
    required: [data, pagination]
    properties:
      data:
        type: array
        items: {}              # Override in specific responses
      pagination:
        $ref: '#/components/schemas/PaginationMeta'

  PaginationMeta:
    type: object
    properties:
      total:
        type: integer
      page:
        type: integer
      perPage:
        type: integer
      totalPages:
        type: integer

parameters:
  PageParam:
    name: page
    in: query
    schema:
      type: integer
      minimum: 1
      default: 1
  PerPageParam:
    name: per_page
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20

Enum Patterns

# String enum
schemas:
  Status:
    type: string
    enum: [active, inactive, suspended]
    description: |
      - `active` — Resource is live and operational
      - `inactive` — Resource exists but is not in use
      - `suspended` — Resource is temporarily disabled

---

Validation Rules

Required Fields Checklist

Common Validation Rules

Format Validators

Common format values and what they validate:

---

Code Generation Integration

Generator Configuration

# openapi-generator config
generatorName: typescript-axios
inputSpec: ./openapi.yaml
outputDir: ./generated/client
additionalProperties:
  supportsES6: true
  npmName: "@myorg/api-client"
  withInterfaces: true

Codegen-Friendly Conventions

---

Versioning in Specs

URL-Based Versioning

servers:
  - url: https://api.example.com/v1
    description: Version 1 (current)
  - url: https://api.example.com/v2
    description: Version 2 (beta)

Deprecation

paths:
  /old-endpoint:
    get:
      deprecated: true
      summary: "[Deprecated] Use /new-endpoint instead"
      description: |
        **Deprecated since v2.3.0.** Will be removed in v3.0.0.
        Use `GET /new-endpoint` instead.

Breaking vs Non-Breaking Changes

---

Reusable Components

Component Categories

Organize components by type for maintainability:

components:
  schemas:          # Data models
  parameters:       # Query, path, header params
  responses:        # Standard responses (404, 500, etc.)
  requestBodies:    # Common request payloads
  headers:          # Standard response headers
  securitySchemes:  # Auth mechanisms
  links:            # Hypermedia links between operations
  callbacks:        # Webhook definitions

Standard Error Response

components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'

    ErrorDetail:
      type: object
      properties:
        field:
          type: string
        reason:
          type: string
        value: {}

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

---

Security Scheme Patterns

Bearer Token (JWT)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

API Key

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

OAuth 2.0

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read:resources: Read access to resources
            write:resources: Write access to resources

Per-Operation Security Override

paths:
  /public/health:
    get:
      security: []       # No auth required (overrides global)
      summary: Health check

  /admin/config:
    put:
      security:
        - bearerAuth: []
        - oauth2: [write:admin]    # Requires elevated scope

---

Examples and Mocking

Inline Examples

schemas:
  User:
    type: object
    properties:
      id:
        type: string
        example: "usr_abc123"
      email:
        type: string
        example: "alice@example.com"

Named Examples (Multiple Scenarios)

paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                active-user:
                  summary: An active user
                  value:
                    id: usr_abc123
                    email: alice@example.com
                    status: active
                suspended-user:
                  summary: A suspended user
                  value:
                    id: usr_xyz789
                    email: bob@example.com
                    status: suspended

Mock Server

Use examples to power mock servers:

# Prism (Stoplight) — generates mock responses from examples
prism mock openapi.yaml

# Runs a local server that returns example responses
# matching the schema and status codes in the spec