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
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
MIT