openapi-design

name	openapi-design
description	Contract-first REST API design with OpenAPI 3.1 specification
allowed-tools	Read, Glob, Grep, Write, Edit, mcp__perplexity__search, mcp__context7__resolve-library-id, mcp__context7__query-docs

OpenAPI Design Skill

When to Use This Skill

Use this skill when:

• Openapi Design tasks - Working on contract-first rest api design with openapi 3.1 specification
• Planning or design - Need guidance on Openapi Design approaches
• Best practices - Want to follow established patterns and standards

Overview

Contract-first REST API design using OpenAPI 3.1 specification for consistent, well-documented APIs.

MANDATORY: Documentation-First Approach

Before creating OpenAPI specifications:

1. Invoke docs-management skill for API design patterns
2. Verify OpenAPI 3.1 syntax via MCP servers (context7 for latest spec)
3. Base all guidance on OpenAPI 3.1 specification

Contract-First Approach

Why Contract-First?

1. Design before implementation: Think through API before coding
2. Parallel development: Frontend and backend can work simultaneously
3. Clear contract: Unambiguous specification for all parties
4. Auto-generation: Generate clients, servers, documentation
5. Validation: Validate requests/responses against schema

Workflow

Requirements → OpenAPI Spec → Review → Generate → Implement → Test
     ↑                                                      ↓
     ←←←←←←←←←←←←← Iterate as needed ←←←←←←←←←←←←←←←←←←←←←←

OpenAPI 3.1 Structure

Basic Template

openapi: 3.1.0
info:
  title: Order Management API
  description: |
    API for managing customer orders in the e-commerce platform.

    ## Features
    - Create and manage orders
    - Track order status
    - Process payments
  version: 1.0.0
  contact:
    name: API Team
    email: [e-mail]
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api.staging.example.com/v1
    description: Staging
  - url: http://localhost:5000/v1
    description: Development

tags:
  -  
       
    
        


  


  
    
  
    
  
    
  
    

Paths Definition

paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      description: Retrieve a paginated list of orders with optional filtering
      tags:
        - Orders
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
        - name: status
          in: query
          description: Filter by order status
          schema:
            $ref: '#/components/schemas/OrderStatus'
        - name: customerId
          in: query
          description: Filter by customer ID
          schema:
             
             
      
        
            
          
            
              
                 
        
           
        
           

    
       
        
             
      
         
      
          []
      
         
        
          
            
               
            
              
                  
                
                   
                  
                      
                       
      
        
            
          
            
              
                 
          
            
                  
              
                 
                 
        
           
        
           
        
           

  
    
        
         
         
           
        
           
           

    
       
          
      
         
      
          []
      
        
            
          
            
              
                 
        
           

    
       
        
               
      
         
      
          []
      
         
        
          
            
               
      
        
            
          
            
              
                 
        
           
        
           
        
           

    
       
        
              
      
         
      
          []
      
        
            
        
           
        
           

  
    
       
        
               
      
         
      
          []
      
          
           
           
          
             
             
      
        
            
          
            
              
                 
        
              
          
            
              
                 
        
           

Components Definition

components:
  schemas:
    # Enums
    OrderStatus:
      type: string
      enum:
        - draft
        - submitted
        - paid
        - shipped
        - delivered
        - cancelled
      description: Current status of the order

    # Value Objects
    Money:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          format: decimal
          minimum: 0
          example: 99.99
        currency:
          type: string
          pattern: '^[A-Z]{3}$'
          example: USD

    # Entities
    Order:
      type: object
      
         
         
         
         
      
        
           
           
           
        
           
           
        
           
        
           
          
             
        
           
        
           
        
           
        
           
           
           
        
           
           
           

    
       
      
         
         
         
         
      
        
           
           
           
        
           
        
           
        
           
           
           
        
           
        
           
           

    
    
       
      
         
      
        
           
           
        
           
          
             

    
       
      
         
         
      
        
           
        
           
           

    
       
      
        
           
           

    
      
          
          
          
            
               

    
       
      
        
           
           
        
           
           
        
           
           

    
       
      
         
         
      
        
           
          
             
        
           

    
       
      
         
         
         
         
      
        
           
           
        
           
           
           
        
           
           
        
           
           

    
    
       
      
         
         
         
      
        
           
           
                
        
           
             
        
           
             
        
           
            
        
           
           
               
        
           
          
             
            
               
              

  
    
       
       
         
      
         
         
         

    
       
       
           
      
         
         
         
         

  
    
        
      
        
          
             

    
        
      
        
          
             

    
        
      
        
          
             

    
         
      
        
          
             

    
             
      
        
          
             

    
        
      
        
          
             

  
    
       
       
       
           

    
       
       
       
           

Design Best Practices

Naming Conventions

# Use camelCase for properties
customerId: string  # ✓ Good
customer_id: string # ✗ Avoid

# Use plural for collections
/orders          # ✓ Good
/order           # ✗ Avoid

# Use nouns for resources
/orders          # ✓ Good
/getOrders       # ✗ Avoid

# Use kebab-case for multi-word paths
/line-items      # ✓ Good
/lineItems       # ✗ Avoid

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Retrieve resource(s)	Yes	Yes
POST	Create resource	No	No
PUT	Replace resource	Yes	No
PATCH	Partial update	No*	No
DELETE	Remove resource	Yes	No

Status Codes

Code	Use For
200	Successful GET, PUT, PATCH
201	Successful POST (resource created)
204	Successful DELETE (no content)
400	Malformed request syntax
401	Authentication required
403	Authenticated but not authorized
404	Resource not found
409	Conflict (state transition, duplicate)
422	Validation error
500	Server error

Versioning Strategies

# URL Path (recommended for breaking changes)
servers:
  - url: https://api.example.com/v1

# Header-based
parameters:
  - name: API-Version
    in: header
    schema:
      type: string
      enum: ['2024-01-01', '2024-06-01']

Validation

JSON Schema Validation

# Use constraints
quantity:
  type: integer
  minimum: 1
  maximum: 1000

email:
  type: string
  format: email
  maxLength: 255

productCode:
  type: string
  pattern: '^[A-Z]{3}-\d{6}$'

# Use enums for known values
status:
  type: string
  enum: [draft, submitted, paid]

# Use nullable for optional fields (OpenAPI 3.1)
middleName:
  type: ['string', 'null']

Workflow

When designing OpenAPI contracts:

1. Understand requirements: What operations are needed?
2. Design resources: Identify entities and relationships
3. Define schemas: Create reusable component schemas
4. Specify endpoints: Define paths and operations
5. Add security: Configure authentication/authorization
6. Document examples: Add request/response examples
7. Validate: Use linting tools (Spectral, etc.)
8. Review: Get team feedback before implementation

References

For detailed guidance:

• OpenAPI 3.1 Specification - Official OpenAPI specification
• RFC 7231 - HTTP Semantics - HTTP methods and status codes
• RFC 7807 - Problem Details - Standard error response format
• Spectral - OpenAPI linting tool
• OpenAPI Generator - Client/server code generation

---

Last Updated: 2025-12-26