openapi

What I do

• Design OpenAPI specifications
• Create API documentation
• Define schemas and data models
• Document authentication
• Handle pagination and filtering
• Use advanced OpenAPI features
• Generate client SDKs
• Test with OpenAPI

When to use me

When creating API specifications or OpenAPI documentation.

OpenAPI Structure

openapi: 3.0.3
info:
  title: Pet Store API
  description: |
    A sample API for managing pets.
    
    ## Features
    - List pets
    - Add new pets
    - Update pet information
    - Place orders
    
    ## Authentication
    All endpoints require Bearer token authentication.
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: http://localhost:8000/api/v1
    description: Local development

tags:
  - name: Pets
    description: Pet management operations
  - name: Store
    description: Store operations
  - name: Users
    description: User management

Paths and Operations

paths:
  /pets:
    get:
      summary: List all pets
      description: Returns a paginated list of pets
      tags:
        - Pets
      operationId: listPets
      parameters:
        - name: status
          in: query
          description: Filter by pet status
          schema:
            type: string
            enum:
              - available
              - pending
              - sold
        - name: limit
          in: query
          description: Maximum number of pets to return
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Number of pets to skip
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    
    post:
      summary: Create a new pet
      description: Add a new pet to the store
      tags:
        - Pets
      operationId: createPet
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePetRequest'
      responses:
        '201':
          description: Pet created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

Components and Schemas

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
        - status
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: "Fluffy"
        status:
          type: string
          enum:
            - available
            - pending
            - sold
          example: "available"
        category:
          $ref: '#/components/schemas/Category'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        photoUrls:
          type: array
          items:
            type: string
            format: uri
          maxItems: 10
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    
    CreatePetRequest:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        status:
          type: string
          enum:
            - available
            - pending
            - sold
        categoryId:
          type: integer
          format: int64
        tags:
          type: array
          items:
            type: string
        photoUrls:
          type: array
          items:
            type: string
            format: uri
          maxItems: 10
    
    PetListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Pet'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
    
    Pagination:
      type: object
      properties:
        total:
          type: integer
          format: int64
        limit:
          type: integer
        offset:
          type: integer
        hasMore:
          type: boolean

Authentication

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication
    
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    
    OAuth2Password:
      type: oauth2
      flows:
        password:
          tokenUrl: /api/v1/auth/token
          scopes:
            read: Read access
            write: Write access

security:
  - BearerAuth: []
  - ApiKeyAuth: []

Advanced Features

# Callbacks
paths:
  /orders:
    post:
      summary: Create an order
      callbacks:
        orderCompleted:
          '$ref': '#/components/callbacks/OrderCompleted'
        orderShipped:
          '$ref': '#/components/callbacks/OrderShipped'

callbacks:
  OrderCompleted:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          description: Order completed callback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCallback'
        responses:
          '200':
            description: Callback received successfully

# Links
paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          links:
            userOrders:
              operationId: getUserOrders
              parameters:
                userId: '$request.path.userId'

# Webhooks
webhooks:
  newOrder:
    post:
      summary: Receive new order notifications
      operationId: newOrderWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Webhook received

Documentation Best Practices

1. Write clear summaries
   - One-line description
   - What the endpoint does

2. Provide detailed descriptions
   - Explain behavior
   - Document edge cases

3. Use proper examples
   - Request examples
   - Response examples
   - Error examples

4. Document all parameters
   - Required vs optional
   - Valid values
   - Default values

5. Define error responses
   - Common errors
   - Error codes
   - Error messages

6. Use tags to organize
   - Group by resource
   - Group by functionality

7. Keep it up to date
   - Update on code changes
   - Version documentation

8. Add getting started
   - Authentication guide
   - Base URL
   - Rate limits

Code Generation

# Generate Python client
openapi-generator generate \
  -i openapi.yaml \
  -g python \
  -o ./clients/python \
  --additional-properties=pythonLibraryName=petshop

# Generate TypeScript client
openapi-generator generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./clients/typescript

# Generate Go server
openapi-generator generate \
  -i openapi.yaml \
  -g go-gin-server \
  -o ./server/go

# Generate Postman collection
openapi-generator generate \
  -i openapi.yaml \
  -g postman-collection \
  -o ./docs/postman.json

Validation with OpenAPI

from openapi_spec_validator import validate
from openapi_spec_validator.versions import consts as validator_versions


def validate_openapi_spec(spec_path: str) -> bool:
    """Validate OpenAPI specification file."""
    with open(spec_path, 'r') as f:
        spec_dict = yaml.safe_load(f)
    
    try:
        validate(spec_dict)
        return True
    except Exception as e:
        print(f"Validation error: {e}")
        return False


def check_coverage(spec: dict) -> dict:
    """Check API coverage against requirements."""
    paths = spec.get('paths', {})
    
    required_endpoints = [
        '/users',
        '/users/{id}',
        '/pets',
        '/pets/{id}',
    ]
    
    existing = []
    missing = []
    
    for endpoint in required_endpoints:
        if endpoint in paths:
            existing.append(endpoint)
        else:
            missing.append(endpoint)
    
    return {
        'existing': existing,
        'missing': missing,
        'coverage': len(existing) / len(required_endpoints),
    }