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

```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 <token>` header.

### API Key

```bash
openapi-mock start openapi.yaml --auth api_key
```

Requests require either:
- `X-API-Key: <key>` header
- `Authorization: ApiKey <key>` header

### Basic Authentication

```bash
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:

```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