openapi-spec-generation

name	openapi-spec-generation
description	Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.

OpenAPI Spec Generation

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

When to Use This Skill

• Creating API documentation from scratch
• Generating OpenAPI specs from existing code
• Designing API contracts (design-first approach)
• Validating API implementations against specs
• Generating client SDKs from specs
• Setting up API documentation portals

Core Concepts

1. OpenAPI 3.1 Structure

openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...

2. Design Approaches

Approach	Description	Best For
Design-First	Write spec before code	New APIs, contracts
Code-First	Generate spec from code	Existing APIs
Hybrid	Annotate code, generate spec	Evolving APIs

Templates

Template 1: Complete API Specification

openapi: 3.1.0
info:
  title: User Management API
  description: |
    API for managing users and their profiles.

    ## Authentication
    All endpoints require Bearer token authentication.

    ## Rate Limiting
    - 1000 requests per minute for standard tier
    - 10000 requests per minute for enterprise tier
  version: 2.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: https://api.example.com/v2
    description: Production
    
     
    
      


    
       
    
       
    
      


  
    
       
         
               
      
         
      
          
          
          
           
              
          
             
          
           
               
          
             
             
             
      
        
            
          
            
              
                 
              
                
                   
        
           
        
           
        
           
      
          []

    
       
          
               
      
         
      
         
        
          
            
               
            
              
                  
                
                   
                    
                   
              
                  
                
                   
                    
                   
      
        
             
          
            
              
                 
          
            
                  
              
                 
                 
        
           
        
             
          
            
              
                 
      
          []

  
    
        

    
       
          
      
         
      
        
            
          
            
              
                 
        
           
      
          []

    
       
        
      
         
      
         
        
          
            
               
      
        
            
          
            
              
                 
        
           
        
           
      
          []

    
       
        
      
         
         
      
        
            
        
           
      
          []
          []


  
    
       
      
         
         
         
         
         
      
        
           
           
           
             
        
           
           
             
        
           
           
           
             
        
           
        
           
           [, , ]
           
        
           
           
           
        
           
           
            
        
           
           
           
        
           
           
           

    
       
       [, , , ]
         

    
       
      
         
         
      
        
           
           
        
           
           
           
        
           
           [, , ]
           
        
           
           

    
       
       
      
        
           
           
           
        
           
        
           
           [, , ]
        
           
           

    
       
      
         
         
      
        
           
          
             
        
           

    
       
      
         
         
         
         
      
        
           
           
        
           
           
           
        
           
           
        
           
           
        
           
        
           

    
       
      
         
         
      
        
           
               
        
           
             
        
           
          
             
            
              
                 
              
                 
        
           
              

  
    
       
       
       
        
      
         
         

    
       
       
         
      
         
         
         

    
       
       
         
      
         
         
         
         

  
    
        
      
        
          
             
          
             
               
            
                
                      

    
        
      
        
          
             
          
             
              

    
         
      
        
          
             
          
             
               

    
         
      
        
          
             
      
        
               
          
             
        
              
          
             
        
              
          
             

  
    
      
        
            
             
             
             
             
             
        
           
           
           
           
           
           

  
    
       
       
       
          

    
       
       
       
           


    []

Template 2: Code-First Generation (Python/FastAPI)

# FastAPI with automatic OpenAPI generation
from fastapi import FastAPI, HTTPException, Query, Path, Depends
from pydantic import BaseModel, Field, EmailStr
from typing import Optional, List
from datetime import datetime
from uuid import UUID
from enum import Enum

app = FastAPI(
    title="User Management API",
    description="API for managing users and profiles",
    version="2.0.0",
    openapi_tags=[
        {"name": "Users", "description": "User operations"},
        {"name": "Profiles", "description": "Profile operations"},
    ],
    servers=[
        {"url": "https://api.example.com/v2", "description": "Production"},
        {"url": "http://localhost:8000", "description": "Development"},
    ],
)

# Enums
class UserStatus(str, Enum):
    active = "active"
    inactive = "inactive"
    suspended = "suspended"
    pending = "pending"

class UserRole(str, Enum):
    user = "user"
    moderator = "moderator"
    admin = 


 ():
    email: EmailStr = Field(..., description=)
    name:  = Field(..., min_length=, max_length=, description=)

 ():
    role: UserRole = Field(default=UserRole.user)
    metadata: [] = Field(default=, description=)

    model_config = {
        : {
            : [
                {
                    : ,
                    : ,
                    : 
                }
            ]
        }
    }

 ():
    name: [] = Field(, min_length=, max_length=)
    status: [UserStatus] = 
    role: [UserRole] = 
    metadata: [] = 

 ():
    : UUID = Field(..., description=)
    status: UserStatus
    role: UserRole
    avatar: [] = Field(, description=)
    metadata: [] = 
    created_at: datetime = Field(..., alias=)
    updated_at: [datetime] = Field(, alias=)

    model_config = {: }

 ():
    page:  = Field(..., ge=)
    limit:  = Field(..., ge=, le=)
    total:  = Field(..., ge=)
    total_pages:  = Field(..., ge=, alias=)
    has_next:  = Field(..., alias=)
    has_prev:  = Field(..., alias=)

 ():
    data: [User]
    pagination: Pagination

 ():
    field: 
    message: 

 ():
    code:  = Field(..., description=)
    message:  = Field(..., description=)
    details: [[ErrorDetail]] = 
    request_id: [] = Field(, alias=)



  ():
    
    
    


  ():
    
    


  ():
    
    


  ():
    
    


  ():
    
    


 __name__ == :
     json
    (json.dumps(app.openapi(), indent=))

Template 3: Code-First (TypeScript/Express with tsoa)

// tsoa generates OpenAPI from TypeScript decorators

import {
  Controller,
  Get,
  Post,
  Patch,
  Delete,
  Route,
  Path,
  Query,
  Body,
  Response,
  SuccessResponse,
  Tags,
  Security,
  Example,
} from "tsoa";

// Models
interface User {
  /** Unique identifier */
  id: string;
  /** User email address */
  email: string;
  /** Display name */
  name: string;
  status: UserStatus;
  role: UserRole;
  /** Avatar URL */
  avatar?: string;
  /** Custom metadata */
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt?: Date;
}

enum UserStatus {
  Active = "active",
  Inactive = ,
   = ,
   = ,
}

  {
   = ,
   = ,
   = ,
}

  {
  : ;
  : ;
  ?: ;
  ?: <, >;
}

  {
  ?: ;
  ?: ;
  ?: ;
  ?: <, >;
}

  {
  : ;
  : ;
  : ;
  : ;
  : ;
  : ;
}

  {
  : [];
  : ;
}

  {
  : ;
  : ;
  ?: { : ; :  }[];
  ?: ;
}

()
()
     {
  
  ()
  ()
  <>(, )
  <>(, )
  <>({
    : [
      {
        : ,
        : ,
        : ,
        : .,
        : .,
        :  (),
      },
    ],
    : {
      : ,
      : ,
      : ,
      : ,
      : ,
      : ,
    },
  })
    (
    () :  = ,
    () :  = ,
    () ?: ,
    () ?: 
  ): <> {
    
      ();
  }

  
  ()
  ()
  (, )
  <>(, )
  <>(, )
    (
    () : 
  ): <> {
    .();
      ();
  }

  
  ()
  ()
  <>(, )
    (
    () : 
  ): <> {
      ();
  }

  
  ()
  ()
  <>(, )
  <>(, )
    (
    () : ,
    () : 
  ): <> {
      ();
  }

  
  ()
  (, )
  ()
  (, )
  <>(, )
    (
    () : 
  ): <> {
    .();
  }
}

Template 4: Validation & Linting

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

# Spectral ruleset (.spectral.yaml)
cat > .spectral.yaml << 'EOF'
extends: ["spectral:oas", "spectral:asyncapi"]

rules:
  # Enforce operation IDs
  operation-operationId: error

  # Require descriptions
  operation-description: warn
  info-description: error

  # Naming conventions
  operation-operationId-valid-in-url: true

  # Security
  operation-security-defined: error

  # Response codes
  operation-success-response: error

  # Custom rules
  path-params-snake-case:
    description: Path parameters should be snake_case
    severity: warn
    given: "$.paths[*].parameters[?(@.in == 'path')].name"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"

  schema-properties-camelCase:
    description: Schema properties should be camelCase
    severity: warn
    given: "$.components.schemas[*].properties[*]~"
    then:
      function: casing
      functionOptions:
        type: camel
EOF

# Run Spectral
spectral lint openapi.yaml

# Redocly config (redocly.yaml)
cat > redocly.yaml << 'EOF'
extends:
  - recommended

rules:
  no-invalid-media-type-examples: error
  no-invalid-schema-examples: error
  operation-4xx-response: warn
  request-mime-type:
    severity: error
    allowedValues:
      - application/json
  response-mime-type:
    severity: error
    allowedValues:
      - application/json
      - application/problem+json

theme:
  openapi:
    generateCodeSamples:
      languages:
        - lang: curl
        - lang: python
        - lang: javascript
EOF

# Run Redocly
redocly lint openapi.yaml
redocly bundle openapi.yaml -o bundled.yaml
redocly preview-docs openapi.yaml

SDK Generation

# OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/typescript-client \
  --additional-properties=supportsES6=true,npmName=@myorg/api-client

# Generate Python client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client \
  --additional-properties=packageName=api_client

# Generate Go client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g go \
  -o ./generated/go-client

Best Practices

Do's

• Use $ref - Reuse schemas, parameters, responses
• Add examples - Real-world values help consumers
• Document errors - All possible error codes
• Version your API - In URL or header
• Use semantic versioning - For spec changes

Don'ts

• Don't use generic descriptions - Be specific
• Don't skip security - Define all schemes
• Don't forget nullable - Be explicit about null
• Don't mix styles - Consistent naming throughout
• Don't hardcode URLs - Use server variables

Resources

• OpenAPI 3.1 Specification
• Swagger Editor
• Redocly
• Spectral