openapi-burrito

Wrap your OpenAPI specs in type-safe Python clients

Table of Contents

• Quick Start
• Features
• Installation
• Documentation
• Examples
• Star History

Quick Start

# Install
uv tool install openapi-burrito

# Generate
openapi-burrito generate openapi.json -o ./my_client

import asyncio

from my_client import AsyncClient


async def main():
    api = AsyncClient(base_url="https://api.example.com")

    # Path-first API: type-checked paths and snake_case parameters
    res = await api.GET("/users/{user_id}", user_id=123)

    if res.is_success:
        print(res.data)
    else:
        print(f"Error {res.status_code}: {res.error}")

    # Or let errors raise: unwrap() returns the typed body directly
    user = (await api.GET("/users/{user_id}", user_id=123)).unwrap()


asyncio.run(main())

Prefer sync? Generate with --client sync and drop the awaits — same paths, same overloads, httpx.Client underneath:

from my_client import Client

api = Client(base_url="https://api.example.com")
res = api.GET("/users/{user_id}", user_id=123)

Features

• Path-First API - Call endpoints by path literal (api.GET("/users/{user_id}")), with full IDE autocomplete for paths and parameters
• Type-Safe - TypedDict models and @overload signatures; generated code passes mypy --strict
• Async by Default - AsyncClient out of the box; --client sync or -c async -c sync when you need the synchronous Client too
• Zero Runtime - Generated code is yours; its only dependency is httpx
• httpx-Based - Connection pooling, timeouts, all httpx client features
• Middleware System - Logging, retry, auth via composable middleware
• Snake Case Params - Path parameters auto-converted to Python style ({userId} → {user_id})

Philosophy: Types Without Runtime Magic

This library has exactly one opinion: your types should come from the spec, and your runtime should stay out of the way.

• Dicts in, dicts out. Responses are plain dicts typed as TypedDict — no model classes to instantiate, serialize, or fight with. res.data IS the parsed JSON. This is what makes the zero-runtime promise possible: where model classes need a deserialization layer (and that layer needs a runtime dependency), a TypedDict is erased at runtime — nothing to construct, no per-request overhead, nothing to import but httpx.
• No validation, no coercion. The generated client does not validate payloads against the schema and does not convert strings to datetime. Your type checker verifies structure at development time; at runtime you get what the API sent, untouched.
• No inheritance hooks, no plugins, no config file. One command in, one small readable package out.

If you want runtime validation and rich models, you want a pydantic-based generator like openapi-python-client — that's a great tool with a different philosophy. openapi-burrito is for when you'd rather have the thinnest possible typed layer over httpx.

If you build FastAPI services, this will feel like home: the same httpx + type-hints + async idioms you already use, pointed at the APIs you consume instead of the ones you serve.

Installation

For Users

# As a CLI tool (recommended)
uv tool install openapi-burrito

# With preview server support (Swagger UI, Redoc)
uv tool install openapi-burrito[preview]

For Developers

# Clone and install all dev dependencies
git clone https://github.com/simon-lund/openapi-burrito.git
cd openapi-burrito
make install

# Run linting and type checks
make lint

# Run tests
make test

Security

Code generators turn untrusted input into code, so the design has to make injection impossible rather than filter it out. Always review untrusted specs before generating anyway.

How spec text reaches generated code

Nothing from the spec is concatenated into source as-is. Every value takes one of these paths:

As defense in depth, every emitted .py file must pass compile() and the pyproject.toml must parse as TOML before anything is written to disk — malformed output aborts generation instead of landing in your project.

A malicious spec could attempt injection like:

components:
  schemas:
    "User:\n    pass\nimport os; os.system('rm -rf /')  # ":
      type: object

While this generator escapes such payloads, the safest approach is to only generate clients from trusted sources.

See CVE-2020-15142 for an example of this vulnerability class in other generators.

What a spec can reach

Whatever a $ref reads ends up in the generated code. So a spec may only reference files inside its own folder, and a spec loaded from a URL may only reference itself. Anything else (other URLs, files elsewhere on disk) is refused before it is read, unless you pass --allow-external-refs for a spec you trust.

Path arguments

Generated clients percent-encode path arguments, so id="../../admin" stays one URL segment and cannot reach another endpoint. . and .. raise ValueError, because no encoding keeps them from being normalized away.

Documentation

Examples

See the examples/ directory:

• Petstore - Classic Swagger Petstore API
• Artifacts MMO - Game API with complex schemas

Star History