openapi-burrito 0.1.0

A lightweight CLI tool to generate a type-safe Python client from an OpenAPI specification.

[!WARNING] Early Development: This project is under active development. APIs may change.

---

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

from my_client import Client

api = Client(base_url="https://api.example.com")

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

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

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
• Zero Runtime - Generated code is yours, no runtime dependency on this tool
• httpx-Based - Async support, connection pooling, all httpx features
• Middleware System - Logging, retry, auth via composable middleware
• Snake Case Params - Path parameters auto-converted to Python style ({userId} → {user_id})

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

This generator sanitizes identifiers and string literals to prevent code injection from malformed OpenAPI specs. However, always review untrusted specs before generating.

Parser Safety Audit

All fields output by the parser are validated/sanitized:

Field	Validation	Notes
Model/param names	sanitize(mode="id")	Converted to valid Python identifiers
Paths	sanitize(mode="str")	String-escaped for literals
Descriptions/docs	sanitize(mode="doc")	Docstring-escaped
type strings	Type translator	Built from validated schema types
method	HTTPMethod enum	Only known HTTP methods allowed
in (param location)	Enum check	Only path|query|header|cookie
required, read_only, write_only	bool() cast	Forced to boolean
default	repr()	Python string representation

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.

Documentation

Guide	Description
Introduction	Installation and basic usage
Authentication	API keys, tokens, OAuth patterns
Middleware	Logging, retry, custom handling
Type System	UNSET, Unknown, NotRequired, limitations
CLI Reference	generate and preview commands
Contributing	Development setup and guidelines

Examples

See the examples/ directory:

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

Star History