openapi-mock-server/.README.md

OpenAPI Mock Server

A CLI tool that generates mock API servers from OpenAPI/Swagger specifications, automatically creating realistic mock responses with field-type-aware fake data generation, configurable response delays, hot-reload support, and optional authentication simulation.

Features

• OpenAPI/Swagger Support: Parse and validate both OpenAPI 3.x and Swagger 2.0 specifications
• Smart Data Generation: Generate realistic mock data based on JSON Schema field types, formats, patterns, and constraints
• Dynamic Route Creation: Automatically create API routes from OpenAPI endpoint definitions
• Hot Reload: Automatically reload the server when the OpenAPI spec file changes
• Configurable Delays: Add response delays to simulate real API latency
• Authentication Simulation: Support for Bearer token, API Key, and Basic authentication
• Configuration Files: Support for YAML/JSON configuration files with environment variable overrides

Installation

# Install from PyPI
pip install openapi-mock-server

# Install from source
pip install -e .

Quick Start

Basic Usage

Start a mock server from an OpenAPI specification:

openapi-mock start path/to/openapi.yaml

By default, the server runs on http://127.0.0.1:8080.

With Options

# Specify port and host
openapi-mock start path/to/openapi.yaml --port 3000 --host 0.0.0.0

# Add response delay (fixed or range)
openapi-mock start path/to/openapi.yaml --delay 0.5
openapi-mock start path/to/openapi.yaml --delay 0.1,1.0

# Enable hot-reload (automatic restart on spec changes)
openapi-mock start path/to/openapi.yaml --watch

# Enable authentication
openapi-mock start path/to/openapi.yaml --auth bearer
openapi-mock start path/to/openapi.yaml --auth api_key
openapi-mock start path/to/openapi.yaml --auth basic

Other Commands

Validate an OpenAPI specification:

openapi-mock validate path/to/openapi.yaml

Display information about an OpenAPI specification:

openapi-mock info path/to/openapi.yaml

Generate a standalone Python file:

openapi-mock generate path/to/openapi.yaml -o mock_server.py

Configuration File

You can use a configuration file to set default options. The tool looks for configuration files in the following order:

1. .openapi-mock.yaml
2. .openapi-mock.yml
3. mock-config.yaml
4. mock-config.yml

Example configuration file:

# .openapi-mock.yaml
host: 0.0.0.0
port: 8080
delay: 0.1,0.5
auth: bearer
watch: true

Environment Variables

You can also use environment variables to override configuration:

Variable	Description
OPENAPI_MOCK_PORT	Port number
OPENAPI_MOCK_HOST	Host address
OPENAPI_MOCK_DELAY	Response delay (e.g., 0.5 or 0.1,1.0)
OPENAPI_MOCK_AUTH	Authentication type

Data Generation

The mock server generates realistic mock data based on your OpenAPI schema:

• String formats: email, date-time, date, uuid, uri, url, phone-number
• String constraints: minLength, maxLength, pattern, enum
• Number constraints: minimum, maximum, multipleOf
• Array constraints: minItems, maxItems
• Object properties: Generates required properties and optionally additional properties

Example schema and generated data:

# OpenAPI Schema
components:
  schemas:
    User:
      type: object
      required:
        - id
        - username
        - email
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
          minLength: 3
          maxLength: 50
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time

Generated response:

{
  "id": 12345,
  "username": "john_doe",
  "email": "john.doe@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

Hot Reload

When using the --watch flag, the server automatically reloads when the OpenAPI specification file changes. This is useful during development when you're iterating on your API design.

The watcher:

• Monitors the spec file for changes
• Gracefully restarts the server
• Debounces rapid changes to avoid unnecessary reloads

Authentication

Bearer Token (JWT)

openapi-mock start openapi.yaml --auth bearer

Requests require the Authorization: Bearer <token> header.

API Key

openapi-mock start openapi.yaml --auth api_key

Requests require either:

• X-API-Key: <key> header
• Authorization: ApiKey <key> header

Basic Authentication

openapi-mock start openapi.yaml --auth basic

Requests require the Authorization: Basic <base64-encoded-credentials> header.

Response Delays

Simulate real API latency by adding response delays:

# Fixed delay of 500ms
openapi-mock start openapi.yaml --delay 0.5

# Random delay between 100ms and 1000ms
openapi-mock start openapi.yaml --delay 0.1,1.0

Development

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src

# Run integration tests
pytest tests/ -k "integration" --tb=short

Project Structure

openapi-mock-server/
├── src/
│   └── openapi_mock/
│       ├── cli/           # CLI commands and interface
│       ├── core/          # Core utilities (spec parsing, config)
│       ├── generators/    # Data generation logic
│       └── server/        # FastAPI server and middleware
├── tests/
│   ├── conftest.py        # Pytest fixtures
│   ├── test_*.py          # Unit tests
│   └── fixtures/          # Test fixtures
├── pyproject.toml
└── requirements.txt

Requirements

• Python 3.9+
• click >= 8.0
• pyyaml >= 6.0
• faker >= 19.0
• fastapi >= 0.100
• uvicorn >= 0.23
• openapi-spec-validator >= 0.6
• watchdog >= 3.0

License

MIT License