api-mock-cli/README.md

# API Mock CLI

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![Test Status](https://img.shields.io/badge/tests-passing-green)](https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli/actions)

A powerful CLI tool that converts API definitions into shareable local mock servers. Developers provide endpoint definitions with response templates, and the tool automatically generates a fully functional mock server with intelligent routing, request validation, and dynamic response templating.

## Features

- **Automatic Mock Server**: Spin up a FastAPI-based mock server from YAML/JSON endpoint definitions
- **Smart Endpoint Routing**: Pattern matching for endpoints including path parameters and HTTP methods
- **Shareable Local URLs**: Expose your local server via ngrok tunneling for team collaboration
- **Request Validation**: Validate incoming requests against JSON schemas
- **Dynamic Response Templating**: Generate responses using Jinja2 variable substitution
- **Offline Mode**: Run without external dependencies for testing environments

## Quick Start

### Installation

```bash
pip install api-mock-cli
```

Or from source:

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli.git
cd api-mock-cli
pip install -e .
```

### Basic Usage

1. **Initialize a new mock project:**

```bash
api-mock init --name my-api
cd my-api
```

2. **Start the mock server:**

```bash
api-mock start
```

3. **Test your endpoints:**

```bash
curl http://localhost:8000/api/hello
```

## Commands

### init

Create a new mock project structure with predefined templates.

```bash
api-mock init --name my-api [--template basic|full|minimal]
```

**Options:**
- `--name` (required): Name of the mock project
- `--template`: Project template (default: basic)
  - `basic`: Simple single-endpoint setup
  - `full`: Multi-endpoint with validation examples
  - `minimal`: Bare-bones structure

### start

Start the mock server with optional configuration.

```bash
api-mock start [--port 8000] [--host 0.0.0.0] [--offline] [--reload]
```

**Options:**
- `--port`: Server port (default: 8000)
- `--host`: Server host (default: 0.0.0.0)
- `--offline`: Disable ngrok tunneling
- `--reload`: Enable auto-reload on file changes

### stop

Stop the running mock server.

```bash
api-mock stop
```

### generate

Generate a new endpoint definition file.

```bash
api-mock generate EndpointName --method GET --path /api/endpoint
```

**Options:**
- `EndpointName` (required): Name for the new endpoint
- `--method`: HTTP method (GET, POST, PUT, DELETE, PATCH)
- `--path`: URL path for the endpoint

## Configuration

Create a `config.yaml` file in your project root:

```yaml
name: my-mock-api
version: 1.0.0
server:
  port: 8000
  host: 0.0.0.0
  tunnel: true
  offline: false
  reload: true
  log_level: info
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `API_MOCK_PORT` | Server port | 8000 |
| `API_MOCK_HOST` | Server host | 0.0.0.0 |
| `API_MOCK_OFFLINE` | Run without tunneling | false |
| `NGROK_AUTHTOKEN` | ngrok authentication token | - |
| `API_MOCK_LOG_LEVEL` | Logging level | info |

## Endpoint Definition

Define endpoints in `endpoints.yaml`:

```yaml
version: "1.0.0"
endpoints:
  - path: /api/users/{id}
    method: GET
    name: Get User
    description: Retrieve a user by ID
    response:
      status_code: 200
      body:
        id: "{{request.path.id}}"
        name: "John Doe"
        email: "john@example.com"
    validators:
      body:
        type: object
        required: [name, email]
        properties:
          name: {type: string, minLength: 1}
          email: {type: string, format: email}
```

### Response Templating

Use Jinja2 templates for dynamic responses:

| Template | Description |
|----------|-------------|
| `{{request.path.id}}` | Path parameters |
| `{{request.query.page}}` | Query parameters |
| `{{request.body.name}}` | Request body fields |
| `{{request.headers.Authorization}}` | Request headers |
| `{{uuid}}` | Generate UUID v4 |
| `{{timestamp}}` | Current ISO timestamp |
| `{{random_int(1, 100)}}` | Random integer in range |
| `{{random_choice}}` | Random item from list |

### Response Headers

```yaml
response:
  status_code: 201
  headers:
    Content-Type: application/json
    X-Request-Id: "{{uuid}}"
  body:
    success: true
```

### Status Codes

```yaml
response:
  status_code: 404
  body:
    error: "Resource not found"
```

## Project Structure

```
my-api/
├── config.yaml
├── endpoints.yaml
├── responses/
│   └── user.json
├── schemas/
│   └── user.json
└── README.md
```

## Offline Mode

Run the mock server without ngrok tunnel for internal networks or testing:

```bash
api-mock start --offline
```

## Installation for Development

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli.git
cd api-mock-cli

python -m venv venv
source venv/bin/activate

pip install -e ".[dev]"

pytest tests/ -v
ruff check .
```

## Tech Stack

- **FastAPI**: Web framework for building APIs
- **Click**: CLI framework
- **Uvicorn**: ASGI server
- **Pydantic**: Data validation
- **PyNgrok**: ngrok integration for tunneling
- **Jinja2**: Template engine
- **PyYAML**: YAML parsing

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

### v0.1.0 (2024-01-29)

- Initial release
- Basic mock server functionality
- Endpoint routing with path parameters
- Request validation support
- Response templating with Jinja2
- ngrok tunnel integration
- CLI commands: init, start, stop, generate