@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

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

Or use directly with npx:

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

Requirements

• Node.js 14.0 or later (for running the CLI)
• .NET 8.0 or later runtime (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:

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

Then run:

npm run generate:api

With npx (One-off usage or without installation)

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

# 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:

# 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

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="[email protected]")

With FastAPI

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:

from generated.models.user import User

# Create with validation
user = User(name="John", email="[email protected]")

# 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": "[email protected]"}')

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:

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