openapi-design

name	openapi-design
description	Design and document REST APIs using the OpenAPI 3.1 specification — schemas, security definitions, response codes, examples, and SDK generation. Outputs complete OpenAPI specs, documentation, and validation tooling.
argument-hint	["API domain","authentication method","consumer base","documentation requirements"]
allowed-tools	Read, Write, Bash

OpenAPI Design

OpenAPI is the contract between your API and its consumers. A well-designed OpenAPI spec is accurate (matches actual API behavior), complete (all endpoints, all error codes), and useful (rich examples, clear descriptions). It drives documentation, SDK generation, mock servers, and contract testing.

Design Principles

• Design spec first — write the OpenAPI spec before implementation; the spec is the design document.
• Be prescriptive about errors — document all error codes, not just 200; consumers need to handle failures.
• Use $ref for reuse — schemas, parameters, and responses defined once and referenced everywhere.
• Rich examples — every endpoint should have request and response examples, not just schemas.
• Semantic versioning in the URL — /api/v1/ not /api/.

Process

1. Define the domain model — identify the core resources and their relationships.
2. Design endpoints — CRUD + actions; resource-oriented URLs.
3. Define schemas with validation — types, formats, required fields, patterns, constraints.
4. Specify error responses — 400, 401, 403, 404, 409, 422, 429, 500 for every endpoint.
5. Add security definitions — bearer token, API key, OAuth flows.
6. Write examples — realistic, not string and 0.
7. Validate the spec — lint against OpenAPI rules.
8. Generate SDK and docs — from spec, not from code.

Output Format

Complete OpenAPI 3.1 Spec

# openapi.yaml
openapi: "3.1.0"

info:
  title: Orders API
  version: "2.0.0"
  description: |
    The Orders API manages order creation, fulfillment, and tracking.
    
    ## Authentication
    All endpoints require a Bearer token. Obtain a token via POST /auth/token.
    
    ## Rate Limiting
    Requests are limited by plan: Starter 60/min, Growth 600/min, Enterprise 6000/min.
    Rate limit status is returned in X-RateLimit-Remaining and X-RateLimit-Reset headers.
  contact:
    name: Platform Team
    email: [e-mail]
    url: https://docs.example.com
  license:
    name: 
   


    
     
    
     


    
      
    
        


    []


  
    
       
       []
        
                  
      
          
          
          
           
          
             
             [, , , , ]
              
          
           
          
             
             
              
          
           
          
             
             
           
      
        
              
          
            
               
          
            
              
                 
              
                
                    
                     
                    
                       
                       
                     
                     
                 
                 
                 
        
           
        
           
        
           
        
           
    
    
       
       []
         
                    
      
         
        
          
            
               
            
               
              
                  
                   
              
                 
                 
                 
                 
                 
      
        
             
          
            
                   
              
                 
               
          
            
              
                 
        
           
        
               
          
            
              
                 
              
                 
                 
                
                   
        
            
          
            
              
                 
              
                 
                 
        
           
        
           

  
    
        
         
         
        
           
           
         
    
    
       
       []
         
      
        
          
            
              
                 
        
           
        
           
        
           


  
    
       
       
       
           
  
  
    
       
       
      
         
         
         
         
    
       
       
      
         
             
  
  
    
              
      
         
  
  
    
       
       [, , , , , , ]
      
        
           
           
             
           
        
           
           [, , , , , ]
        
           
        
           
          
             
           
        
           
           
               
           
        
           
        
           
           
           
        
           
           
        
           
          
            
               
               
            
               
               
    
    
       
       [, ]
      
        
           
          
             
        
           
           
        
           
        
           
                 
    
    
       
       [, ]
      
        
           
           
        
           
          
             
             [, ]
            
              
                 
              
                 
                 
                 
           
           
        
           
        
           
           
                
    
    
       
       [, ]
      
        
           
              
           
        
           
             
        
           
               
        
           
               
    
    
      
          
          
          
            
               
              
                 
                 [, ]
                
                  
                     
                     
                  
                     
                     
                  
                     
                     
    
    
       
       [, , ]
      
        
           
           
        
           
           
           
        
           
           
        
           
           
        
           
           
        
           
           
               
           
    
    
       
       [, ]
      
        
           
           
        
           
           
  
  
    
        
      
        
          
             
          
             
             
    
    
        
      
        
          
             
          
             
             
    
    
         
      
        
          
             
          
             
             
    
    
        
      
        
          
             
    
    
         
      
        
          
             
    
    
         
      
        
          
             
               
      
        
          
             
          
             
             
    
    
         
      
        
          
             
          
             
             
             

Spec Validation CI

#!/bin/bash
# scripts/validate-openapi.sh
set -e

# Install tools
npm install -g @redocly/cli spectral-cli

# Validate OpenAPI spec structure
redocly lint openapi.yaml

# Check spec against style rules
spectral lint openapi.yaml --ruleset .spectral.yaml

# Verify spec matches actual implementation
npx dredd openapi.yaml http://localhost:8000

echo "OpenAPI spec is valid and matches implementation"

Rules

• Design spec first, implement second — the spec is the design document; code implements the spec.
• Every endpoint documents every error — consumers cannot handle errors they don't know about.
• Real examples, not placeholder strings — example: ord_01hx2k3m4n5p6q7r not example: string.
• Machine-readable error codes — error: "product_not_found" enables consumers to handle specific errors programmatically.
• $ref everything reusable — copy-pasting schemas creates inconsistency; use references.
• Validate the spec in CI — a spec that doesn't lint is a spec with bugs.
• Contract tests verify spec matches implementation — Dredd or Schemathesis to catch drift.
• Include idempotency key on mutations — document it in the spec so SDK generators can surface it.
• Deprecate in the spec before removing — mark operations as deprecated with migration instructions before removing.
• Generate SDKs from spec, not from code — spec-generated SDKs stay in sync; hand-written SDKs drift.