npm package: @metaengine/openapi-python
Description: Generate Python/FastAPI services and models from OpenAPI specifications with Pydantic models, httpx client, and async/await support for Python 3.12+
Author: José A. Saldaña Perez
Latest version: 0.9.0

# @metaengine/openapi-python

Generate Python/FastAPI services and models from OpenAPI specifications.

## Features

- ✅ **Python 3.12+** - Modern Python with type hints
- ✅ **FastAPI** - High-performance async API framework
- ✅ **Pydantic V2** - Optional data validation with type hints (opt-in)
- ✅ **httpx** - Modern async HTTP client
- ✅ **Type Safe** - Full type hint coverage
- ✅ **Async/Await** - Native async support

## Installation

```bash
npm install --save-dev @metaengine/openapi-python
```

Or use directly with npx:

```bash
npx @metaengine/openapi-python <input> <output>
```

## Requirements

- Node.js 14.0 or later (for running the CLI)
- .NET 8.0 or later runtime ([Download](https://dotnet.microsoft.com/download))
- Python 3.12 or later (for using generated code)

## Usage

### With npm scripts (Recommended when installed locally)

If you installed the package with `npm install`, add a script to your `package.json`:

```json
{
  "scripts": {
    "generate:api": "metaengine-openapi-python api.yaml ./src/api --pydantic-models --documentation --camel-case-aliases"
  }
}
```

Then run:
```bash
npm run generate:api
```

### With npx (One-off usage or without installation)

Use `npx` for trying out the tool or in CI/CD pipelines:

```bash
# Recommended (with Pydantic models, documentation, and camelCase aliases)
npx @metaengine/openapi-python api.yaml ./generated \
  --pydantic-models \
  --documentation \
  --camel-case-aliases

# Basic (minimal setup, plain dataclasses)
npx @metaengine/openapi-python api.yaml ./generated

# Filter by tags (only specific endpoints)
npx @metaengine/openapi-python api.yaml ./generated \
  --include-tags users,auth \
  --pydantic-models \
  --documentation

# From URL with Pydantic models
npx @metaengine/openapi-python https://api.example.com/openapi.json ./generated \
  --pydantic-models \
  --documentation \
  --camel-case-aliases
```

**Note:** When the package is installed locally, `npx` will use that version instead of downloading a new one.

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--include-tags <tags>` | Filter by OpenAPI tags (comma-separated, case-insensitive) | - |
| `--service-suffix <suffix>` | Service naming suffix | `Service` |
| `--options-threshold <n>` | Parameter count for options object | `4` |
| `--documentation` | Generate docstring comments | `false` |
| `--pydantic-models` | Enable Pydantic v2 models for validation (opt-in) | `false` |
| `--camel-case-aliases` | Generate camelCase field aliases for Pydantic models | `false` |
| `--strict-validation` | Enable strict OpenAPI validation | `false` |
| `--verbose` | Enable verbose logging | `false` |
| `--help, -h` | Show help message | - |

## Generated Code Structure

```
generated/
├── models/          # Pydantic models
│   ├── user.py
│   ├── order.py
│   └── ...
└── services/        # API service classes
    ├── users_service.py
    ├── orders_service.py
    └── ...
```

## Usage Examples

### Install Dependencies

Install the required Python packages:

```bash
# Basic dependencies
pip install httpx typing-extensions

# Additional dependencies for Pydantic models (when using --pydantic-models)
pip install fastapi pydantic
```

Or add to your `requirements.txt`:
```
# Required
httpx>=0.27.0
typing-extensions>=4.0.0

# Optional: for Pydantic models (--pydantic-models flag)
fastapi>=0.115.0
pydantic>=2.0.0
```

### Basic API Calls

```python
from generated.services.users_service import UsersService

# Initialize service
users_service = UsersService(base_url="https://api.example.com")

# Fetch users
users = await users_service.get_users()

# Create a user
new_user = await users_service.create_user(name="John", email="john@example.com")
```

### With FastAPI

```python
from fastapi import FastAPI, Depends
from generated.services.users_service import UsersService
from generated.models.user import User

app = FastAPI()

def get_users_service():
    return UsersService(base_url="https://api.example.com")

@app.get("/api/users")
async def get_users(service: UsersService = Depends(get_users_service)) -> list[User]:
    return await service.get_users()

@app.post("/api/users")
async def create_user(
    user: User,
    service: UsersService = Depends(get_users_service)
) -> User:
    return await service.create_user(name=user.name, email=user.email)
```

### Pydantic Models (with `--pydantic-models` flag)

When using `--pydantic-models`, generated Pydantic models provide validation and serialization:

```python
from generated.models.user import User

# Create with validation
user = User(name="John", email="john@example.com")

# Serialize to dict
user_dict = user.model_dump()

# Serialize to JSON
user_json = user.model_dump_json()

# Parse from JSON
user = User.model_validate_json('{"name": "John", "email": "john@example.com"}')
```

### CamelCase Aliases (with `--pydantic-models` and `--camel-case-aliases`)

When using both `--pydantic-models` and `--camel-case-aliases`, Pydantic models will accept both snake_case and camelCase:

```python
from generated.models.user import User

# Both work!
user1 = User(first_name="John", last_name="Doe")
user2 = User(firstName="John", lastName="Doe")

# Output is snake_case by default
print(user1.first_name)  # "John"
```

## Framework Support

Currently supports:
- **FastAPI** (default) - High-performance async API framework

Coming soon:
- **Django** - Use `--framework django` (planned)
- **Flask** - Use `--framework flask` (planned)

## Type Hints

All generated code includes complete type hints for:
- Function parameters
- Return types
- Pydantic model fields
- Optional/required fields

Compatible with:
- mypy
- pyright
- pylance

## License

MIT

## Support

For issues and feature requests, please visit:
https://github.com/meta-engine/openapi-python/issues