Files
openapi-mock-server/.README.md
7000pctAUTO 4fb558d90f
Some checks failed
CI / test (push) Has been cancelled
CI / build (push) Has been cancelled
Initial commit: Add OpenAPI Mock Server project
2026-01-30 03:41:35 +00:00

5.9 KiB

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