Initial commit: Add OpenAPI Mock Server project

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