openapi-mock-generator/README.md

# 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

```bash
pip install openapi-mock-generator
```

### From Source

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

### Using Docker

```bash
docker pull openapi-mock-generator:latest
```

## Quick Start

### 1. Create or use an OpenAPI specification

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

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

### 3. Test the endpoint

```bash
curl http://localhost:8080/users
```

## CLI Commands

### serve

Start the mock server.

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

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

```bash
openapi-mock validate [OPTIONS]
```

### test

Test a mock endpoint with a custom request.

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

```bash
openapi-mock routes
```

### info

Display information about the OpenAPI specification.

```bash
openapi-mock info
```

### docker

Build and run Docker container.

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

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

spec:
  file: openapi.yaml
  validate: true
```

## Docker Usage

### Build the image

```bash
docker build -t openapi-mock-generator .
```

### Run the container

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

### With custom port

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

## Examples

### Generate a response

```bash
openapi-mock generate /users get --format json
```

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

### Test with request body

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

### Enable fuzzing mode

```bash
openapi-mock serve --fuzzing --port 8080
```

### Add response delay

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

## API Reference

### Python Library

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

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

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

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

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

```bash
pytest tests/ -v
```

### Run with coverage

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