OpenAPI Mock Generator

A CLI tool that generates realistic mock API responses from OpenAPI/Swagger specifications. Features include schema-based response generation, request validation, configurable delays, fuzzing mode for edge case testing, and Docker support for containerized deployments. Solves the problem of testing API clients without requiring a full backend.

Features

• OpenAPI Spec Parser: Parse and validate OpenAPI 3.0/3.1 and Swagger 2.0 specifications
• Schema-based Response Generation: Generate realistic JSON responses using the Faker library
• Request Validation: Validate headers, query parameters, path parameters, and request bodies
• Configurable Response Delays: Simulate slow APIs for timeout testing
• Fuzzing Mode: Generate edge case responses for resilience testing
• Docker Support: Containerized deployments with multi-stage builds

Installation

From PyPI

pip install openapi-mock-generator

From Source

git clone https://github.com/your-org/openapi-mock-generator.git
cd openapi-mock-generator
pip install -e .

Using Docker

docker pull openapi-mock-generator:latest

Quick Start

1. Create or use an OpenAPI specification

# openapi.yaml
openapi: "3.0.0"
info:
  title: Sample API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    email:
                      type: string

2. Start the mock server

openapi-mock serve --spec-file openapi.yaml --port 8080

3. Test the endpoint

curl http://localhost:8080/users

CLI Commands

serve

Start the mock server.

openapi-mock serve [OPTIONS]

Options:

• --spec-file: Path to OpenAPI specification file (default: openapi.yaml)
• --port: Port to run the mock server on (default: 8080)
• --delay: Response delay in milliseconds (default: 0)
• --fuzzing: Enable fuzzing mode for edge case testing
• --seed: Random seed for reproducible responses
• --validate-only: Only validate the OpenAPI spec without starting the server

generate

Generate a mock response without starting the server.

openapi-mock generate [PATH] [METHOD] [OPTIONS]

Options:

• --status-code: HTTP status code for response (default: 200)
• --seed: Random seed for reproducible generation
• --format: Output format (json/yaml, default: json)

validate

Validate the OpenAPI specification.

openapi-mock validate [OPTIONS]

test

Test a mock endpoint with a custom request.

openapi-mock test /users --method get --query "page=1" --header "Accept: application/json"

Options:

• --method: HTTP method (get/post/put/delete/patch)
• --query: Query parameters (key=value)
• --header: Headers (key=value)
• --body: Request body (JSON string)
• --fuzz: Use fuzzing mode

routes

List all available routes from the OpenAPI spec.

openapi-mock routes

info

Display information about the OpenAPI specification.

openapi-mock info

docker

Build and run Docker container.

openapi-mock docker --build

Configuration

Environment Variables

Variable	Description	Default
MOCK_PORT	Default port for mock server	8080
MOCK_DELAY	Default response delay (ms)	0
MOCK_SPEC_FILE	Path to OpenAPI spec file	openapi.yaml

Configuration File

Create a mock-config.yaml file:

server:
  port: 8080
  delay: 100
  fuzzing: false
  seed: 42

spec:
  file: openapi.yaml
  validate: true

Docker Usage

Build the image

docker build -t openapi-mock-generator .

Run the container

docker run -p 8080:8080 -v $(pwd)/openapi.yaml:/app/openapi.yaml:ro openapi-mock-generator

With custom port

docker run -p 3000:8080 -v /path/to/spec.yaml:/app/openapi.yaml:ro openapi-mock-generator --port 8080

Examples

Generate a response

openapi-mock generate /users get --format json

Output:

{
  "status_code": 200,
  "body": [
    {
      "id": 12345,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  ]
}

Test with request body

openapi-mock test /users post --body '{"name": "New User", "email": "new@example.com"}'

Enable fuzzing mode

openapi-mock serve --fuzzing --port 8080

Add response delay

openapi-mock serve --delay 500 --port 8080

API Reference

Python Library

from src.core.parser import OpenAPIParser
from src.core.generator import ResponseGenerator
from src.core.server import MockServer

# Parse OpenAPI spec
parser = OpenAPIParser("openapi.yaml")
spec = parser.load()

# Generate mock response
generator = ResponseGenerator(seed=42)
response = generator.generate(schema)
print(response)

# Start mock server
server = MockServer("openapi.yaml", port=8080, delay=100)
server.start()

OpenAPI Spec Parser

from src.core.parser import OpenAPIParser

parser = OpenAPIParser("openapi.yaml")
spec = parser.load()
paths = parser.get_paths()
schemas = parser.get_schemas()
response_schema = parser.get_response_schema("/users", "get", "200")

Response Generator

from src.core.generator import ResponseGenerator

generator = ResponseGenerator(seed=42)

schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"}
    }
}

response = generator.generate(schema)

Request Validator

from src.core.validator import RequestValidator

validator = RequestValidator(spec)
result = validator.validate_request(
    method="POST",
    path="/users",
    headers={"Content-Type": "application/json"},
    query_params={},
    path_params={},
    body={"name": "Test", "email": "test@example.com"},
    operation_spec=operation
)

Fuzzer

from src.core.fuzzer import Fuzzer

fuzzer = Fuzzer(seed=42)
fuzzed_data = fuzzer.fuzz_schema(schema)
edge_case = fuzzer.create_edge_case_response(schema)

Testing

Run tests

pytest tests/ -v

Run with coverage

pytest tests/ --cov=src --cov-report=term-missing

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT