openapi-spec-writer

name	openapi-spec-writer
description	Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract.
version	1.0.0
metadata	{"category":"documentation","tags":["openapi","swagger","api-documentation","rest","api-design"],"pairs-with":[{"skill":"api-architect","reason":"API design decisions are formalized and documented through OpenAPI specifications"},{"skill":"rest-api-design","reason":"REST endpoint design and OpenAPI documentation are tightly coupled deliverables"},{"skill":"technical-writer","reason":"API documentation quality depends on technical writing clarity and completeness"}]}

OpenAPI Spec Writer

Overview

Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract.

When to Use

• Creating OpenAPI specifications for new APIs
• Documenting existing REST APIs
• Designing API contracts before implementation
• Generating client SDKs from specs
• Setting up interactive API documentation (Swagger UI, Redoc)
• Validating API responses against schemas
• Migrating from OpenAPI 2.0 (Swagger) to 3.x

Capabilities

Specification Writing

• OpenAPI 3.0 and 3.1 syntax
• Path and operation definitions
• Request/response schemas
• Authentication schemes
• Server configurations

Schema Design

• JSON Schema with OpenAPI extensions
• Reusable component schemas
• Discriminators for polymorphism
• oneOf, anyOf, allOf composition
• Nullable types and defaults

Documentation Quality

• Meaningful descriptions and examples
• Markdown in descriptions
• Request/response examples
• Error response documentation
• Deprecation notices

Tooling Integration

• Swagger UI configuration
• Redoc customization
• Spectral linting rules
• SDK generation setup
• Mock server configuration

Dependencies

Works well with:

• api-architect - API design patterns
• rest-api-design - RESTful conventions
• typescript-pro - Generated client types
• github-actions-pipeline-builder - CI validation

Examples

Complete OpenAPI 3.1 Spec

openapi: 3.1.0
info:
  title: Task Management API
  description: |
    RESTful API for managing tasks and projects.

    ## Authentication
    All endpoints require a Bearer token in the Authorization header.

    ## Rate Limiting
    - 1000 requests per hour per API key
    - Rate limit headers included in all responses
  version: 1.0.0
  contact:
    name: API Support
    email: [e-mail]
    url: https://docs.example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: 
      
    
      
    
      


    
       
    
       


  
    
       
         
               
      
         
      
          
          
          
           
              
          
             
          
           
              
          
             
             
      
        
            
          
            
              
                 
              
                
                   
          
            
              
                 
                     
        
           
        
           

    
       
          
               
      
         
      
         
        
          
            
               
            
              
                  
                
                   
              
                     
                
                   
                   
                   
                   
                   
      
        
             
          
            
              
                 
          
            
              
                 
                 
                   
        
           
        
           
        
           

  
    
        

    
       
           
      
         
      
        
            
          
            
              
                 
        
           

    
       
         
               
      
         
      
         
        
          
            
               
      
        
             
          
            
              
                 
        
           
        
           

    
       
         
      
         
      
        
             
        
           


  
    
       
       
       
           

  
    
       
       
       
         
      
         
         
       

    
       
       
           
      
         
         
         

    
       
       
           
      
         
         
         
         

  
    
       
      
         
         
         
         
         
      
        
           
           
            
           
        
           
           
           
            
        
           
           
               
        
           
        
           
        
           
           
             
        
           
           
              
        
           
           
           
        
           
           
           

    
       
      
         
         
         
         
         
       

    
       
      
         
         
         
         
       

    
       
      
         
      
        
           
           
           
        
           
           
        
           
           
        
           
           
        
           

    
       
       
      
        
           
           
           
        
           
           
        
           
        
           
        
           
           

    
       
      
         
         
      
        
           
          
             
        
           

    
       
      
         
         
         
         
      
        
           
        
           
        
           
        
           
        
           
        
           

    
       
      
         
         
      
        
           
             
        
           
             
        
           
           
             

    
      
          
          
          
            
               
              
                 
                
                  
                     
                  
                     

  
    
           
      
        
          
             
          
             
             

    
        
      
        
          
             
          
             
             

    
         
      
        
          
             
          
             
             

    
        
      
        
          
             
          
             
             
            
                
                 

  
    
      
        
            
             
             
             
             
             
        
           
           
           
           
           
           


    []

Polymorphic Schemas (Discriminator)

components:
  schemas:
    Notification:
      type: object
      required:
        - id
        - type
        - created_at
      discriminator:
        propertyName: type
        mapping:
          email: '#/components/schemas/EmailNotification'
          sms: '#/components/schemas/SmsNotification'
          push: '#/components/schemas/PushNotification'
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum: [email, sms, push]
        created_at:
          type: string
          format: date-time

    EmailNotification:
      allOf:
        - $ref: '#/components/schemas/Notification'
        - type: object
          required:
            - to
            - subject
          
            
               
               
            
               
            
               

    
      
          
          
          
             
             
          
            
               
               
            
               
               

Spectral Linting Rules

# .spectral.yaml
extends: ["spectral:oas"]

rules:
  # Enforce operation IDs
  operation-operationId: error

  # Require descriptions
  operation-description: error
  oas3-schema-description: warn

  # Naming conventions
  path-casing:
    given: "$.paths[*]~"
    then:
      function: casing
      functionOptions:
        type: kebab

  # Security requirements
  operation-security-defined: error

  # Response codes
  operation-success-response: error

  # Custom: require examples
  require-examples:
    message: "Responses should have examples"
    given: "$.paths.*.*.responses.*.content.*.schema"
    then:
      field: example
      function: truthy

Best Practices

1. Use components - Extract reusable schemas, parameters, responses
2. Provide examples - Real-world examples for every schema
3. Meaningful descriptions - Markdown-formatted, explain business context
4. Consistent naming - kebab-case paths, camelCase properties
5. Version your API - Include version in URL or header
6. Document errors - Define all error responses with examples
7. Use operationId - Unique, descriptive IDs for SDK generation
8. Validate with linting - Use Spectral to enforce standards
9. Keep spec in sync - Automate validation in CI

Common Pitfalls

• Missing required fields - Forgetting to mark fields as required
• Inconsistent naming - Mixing snake_case and camelCase
• Generic descriptions - "Returns data" instead of specific details
• No examples - Makes spec hard to understand
• Outdated spec - Spec doesn't match implementation
• Overusing anyOf - Makes schemas hard to understand
• Missing error responses - Only documenting happy path
• No pagination - List endpoints without pagination info