From 4fb558d90fcd979d474472b1f829d44164069e1e Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Fri, 30 Jan 2026 03:41:35 +0000 Subject: [PATCH] Initial commit: Add OpenAPI Mock Server project --- .README.md | 251 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 .README.md diff --git a/.README.md b/.README.md new file mode 100644 index 0000000..7c7e856 --- /dev/null +++ b/.README.md @@ -0,0 +1,251 @@ +# 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 + +```bash +# 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: + +```bash +openapi-mock start path/to/openapi.yaml +``` + +By default, the server runs on `http://127.0.0.1:8080`. + +### With Options + +```bash +# 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: + +```bash +openapi-mock validate path/to/openapi.yaml +``` + +Display information about an OpenAPI specification: + +```bash +openapi-mock info path/to/openapi.yaml +``` + +Generate a standalone Python file: + +```bash +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: + +```yaml +# .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: + +```yaml +# 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: + +```json +{ + "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) + +```bash +openapi-mock start openapi.yaml --auth bearer +``` + +Requests require the `Authorization: Bearer ` header. + +### API Key + +```bash +openapi-mock start openapi.yaml --auth api_key +``` + +Requests require either: +- `X-API-Key: ` header +- `Authorization: ApiKey ` header + +### Basic Authentication + +```bash +openapi-mock start openapi.yaml --auth basic +``` + +Requests require the `Authorization: Basic ` header. + +## Response Delays + +Simulate real API latency by adding response delays: + +```bash +# 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 + +```bash +# 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