🦦 OtterAPI

A cute otter that turns OpenAPI & Swagger specs into type-safe, async Python clients — powered by httpx and Pydantic.

OtterAPI is a sleek Python library that transforms OpenAPI specifications into clean, type-safe client code with Pydantic models and httpx-based HTTP clients.

✨ Features

• Type-Safe Code Generation - Generates Pydantic models and fully typed endpoint functions
• Sync & Async Support - Generate both synchronous and asynchronous API clients
• OpenAPI 3.x Support - Full support for OpenAPI 3.0, 3.1, and 3.2 specifications
• Strict or Lenient Validation - Fail fast on malformed specs, or drop stray fields with --lenient (vendor x-* extensions always preserved)
• Module Splitting - Organize large APIs into multiple organized files
• Pagination - Auto-detect or configure offset, cursor, page, and link-header pagination
• DataFrame Conversion - Generate pandas/polars DataFrame methods for list endpoints
• File Export - Generate CSV, TSV, JSONL, and Parquet streaming helpers
• Response Unwrapping - Transparently unwrap envelope-style responses
• Customizable Client - Generated client class with configurable base URL, timeout, and headers
• Environment Variable Support - Use ${VAR} or ${VAR:-default} syntax in config files

🚀 Quick Start

Installation

pip install otterapi

Basic Usage

1. Create an otter.yml configuration file:

documents:
  - source: https://petstore3.swagger.io/api/v3/openapi.json
    output: petstore_client

2. Generate the client:

otter generate

3. Use the generated code:

from petstore_client import get_pet_by_id, async_get_pet_by_id

# Synchronous usage
pet = get_pet_by_id(pet_id=123)

# Asynchronous usage
import asyncio
pet = asyncio.run(async_get_pet_by_id(pet_id=123))

📝 Configuration

Config File Locations

OtterAPI looks for configuration in this order:

1. Path passed via otter generate -c <path>
2. otter.yaml or otter.yml in the current directory
3. otter.json in the current directory
4. [tool.otterapi] section in pyproject.toml
5. OTTER_SOURCE and OTTER_OUTPUT environment variables

Config File Formats

YAML (recommended):

documents:
  - source: https://api.example.com/openapi.json
    output: ./client

pyproject.toml:

[tool.otterapi]
[[tool.otterapi.documents]]
source = "https://api.example.com/openapi.json"
output = "./client"

JSON:

{
  "documents": [
    { "source": "https://api.example.com/openapi.json", "output": "./client" }
  ]
}

Top-Level Options

These sit at the root of your config file, outside of documents:.

format_output: true
validate_output: true
create_py_typed: true

documents:
  - source: https://api.example.com/openapi.json
    output: ./client

Document Options

Each entry under documents: supports these fields:

Function Naming

By default, endpoint function names come from each operation's operationId. Some specs (notably Swashbuckle/.NET output) reuse a single operationId across many distinct paths, which produces a pile of numerically-suffixed duplicates like feed_changes, feed_changes_2, … feed_changes_43. Set function_naming: path to derive names from the HTTP method and URL path instead, giving distinct, descriptive names:

documents:
  - source: https://api.example.com/swagger.json
    output: ./client
    function_naming: path   # get_v1_feed_trial_changes, get_v1_feed_hcp_profile_changes, ...

Path Filtering

documents:
  - source: https://api.example.com/openapi.json
    output: ./client
    include_paths:
      - /api/v2/**       # only v2 endpoints
    exclude_paths:
      - /internal/*      # skip internal endpoints
      - /admin/**        # skip admin endpoints

Patterns follow standard glob syntax (* = single segment, ** = any depth).

Environment Variable Support

Any string value in a config file can reference environment variables:

documents:
  - source: ${API_SPEC_URL}
    output: ${OUTPUT_DIR:-./client}
    base_url: ${BASE_URL:-https://api.example.com}

You can also configure a single document entirely via environment variables (no config file needed):

🔎 Strict vs Lenient Validation

By default, OtterAPI validates specs strictly: an unrecognized or structurally-invalid field aborts generation with a clear error, catching malformed specs early.

Some real-world specs (especially auto-generated Swagger 2.0 documents) carry stray, non-standard keys. Set lenient: true — or pass --lenient — to drop those fields instead of failing. Each dropped key is reported as a warning.

lenient: true

documents:
  - source: https://api.example.com/openapi.json
    output: ./client

otter generate --lenient

Vendor extensions are always preserved. OpenAPI specification extensions (x-*) are kept in both strict and lenient mode. The only exception is the type-discriminated security-scheme objects (apiKey, http, oauth2, openIdConnect), which still reject unknown keys so their variant stays unambiguous.

📦 Module Splitting

For large APIs, OtterAPI can split generated code into multiple organized modules.

Enabling Module Splitting

documents:
  - source: https://api.example.com/openapi.json
    output: ./client
    module_split:
      enabled: true
      strategy: tag

Splitting Strategies

tag — Split by OpenAPI Tags

module_split:
  enabled: true
  strategy: tag
  min_endpoints: 1

Endpoints tagged ["Users"] go to users.py, ["Orders"] to orders.py, etc.

path — Split by URL Path

module_split:
  enabled: true
  strategy: path
  path_depth: 1
  global_strip_prefixes:
    - /api/v1
    - /api/v2

/api/v1/users/123 → users.py, /api/v1/orders/456 → orders.py.

custom — Explicit Module Mapping

module_split:
  enabled: true
  strategy: custom
  module_map:
    users:
      - /users
      - /users/*
      - /users/**
    orders:
      - /orders/*
    health:
      - /health
      - /ready

hybrid — Combined Strategy (Default)

Tries module_map first, then tags, then path:

module_split:
  enabled: true
  strategy: hybrid
  module_map:
    health:
      - /health
      - /ready

none — All to Fallback

module_split:
  enabled: true
  strategy: none
  fallback_module: api

Module Map Patterns

Nested Module Maps

module_split:
  enabled: true
  strategy: custom
  module_map:
    identity:
      users:
        - /users/*
      auth:
        - /auth/*
        - /login
        - /logout
    billing:
      invoices:
        - /invoices/*
      payments:
        - /payments/*

Advanced Module Definition

module_split:
  enabled: true
  strategy: custom
  module_map:
    v2_api:
      paths:
        - /v2/**
      strip_prefix: /v2
      description: "API v2 endpoints"
      file_name: v2.py          # override the generated filename
      modules:
        users:
          paths:
            - /users/*

Module Split Options Reference

Output Structure

Flat (flat_structure: false, default):

client/
├── __init__.py
├── models.py
├── _client.py
├── client.py
├── users.py
├── orders.py
└── health.py

Nested (flat_structure: false with nested module_map):

client/
├── __init__.py
├── models.py
├── _client.py
├── client.py
├── identity/
│   ├── __init__.py
│   ├── users.py
│   └── auth.py
└── billing/
    ├── __init__.py
    └── invoices.py

📄 Pagination

OtterAPI generates iterator-based pagination methods alongside standard endpoint functions. Paginated endpoints get an _iter suffix variant that yields items one by one, handling page-fetching automatically.

Enabling Pagination

documents:
  - source: https://api.example.com/openapi.json
    output: ./client
    pagination:
      enabled: true

Auto-Detection

When auto_detect: true (the default), OtterAPI inspects each endpoint's parameters. If it finds a matching pair for any pagination style, it generates pagination methods automatically — no per-endpoint config needed.

pagination:
  enabled: true
  auto_detect: true           # default
  default_style: offset       # default; used when auto-detected

Pagination Styles

Global Pagination Options

Per-Endpoint Pagination Options

pagination:
  enabled: true
  endpoints:
    list_users:
      style: cursor
      cursor_param: next_token
      limit_param: max_results
      data_path: data.users
      total_path: meta.total
      next_cursor_path: meta.next_token
      default_page_size: 50
      max_page_size: 200
    get_orders:
      enabled: false            # disable pagination for this endpoint

Usage

from client import list_users_iter, async_list_users_iter

# Iterate all users (handles pagination automatically)
for user in list_users_iter():
    print(user.name)

# Async variant
async for user in async_list_users_iter():
    print(user.name)

📊 DataFrame Conversion

When enabled, list-returning endpoints get additional methods that return pandas or polars DataFrames directly.

Enabling DataFrame Methods

documents:
  - source: https://api.example.com/openapi.json
    output: ./client
    dataframe:
      enabled: true
      pandas: true      # generate _df methods (default: true)
      polars: true      # generate _pl methods (default: false)

Generated Methods

Usage

from client import list_pets_df, list_pets_pl

pdf = list_pets_df("available")
plf = list_pets_pl("available")

# Override the data extraction path at call time
df = list_pets_df("available", path="response.data.pets")

Nested Response Paths

dataframe:
  enabled: true
  pandas: true
  default_path: data.items       # default for all endpoints
  endpoints:
    get_users:
      path: data.users           # override for this endpoint
    get_analytics:
      path: response.events
      polars: true
      pandas: false

DataFrame Options

Per-Endpoint DataFrame Options

💾 File Export

When enabled, list-returning endpoints get streaming export helpers for writing responses directly to files (local or remote via UPath).

Enabling Export

documents:
  - source: https://api.example.com/openapi.json
    output: ./client
    export:
      enabled: true
      formats:
        - csv
        - jsonl

Parquet support requires the pyarrow extra:

pip install otterapi[parquet]

Export Options

Per-Endpoint Export Options

export:
  enabled: true
  formats: [csv, jsonl]
  endpoints:
    list_users:
      formats: [parquet]        # only parquet for this endpoint
      path: data.users
    get_events:
      enabled: false            # disable export for this endpoint

Usage

from client import export_list_users_csv, export_list_users_parquet

# Export directly to a file
export_list_users_csv("output/users.csv")
export_list_users_parquet("s3://my-bucket/users.parquet")  # UPath remote targets work too

🔓 Response Unwrapping

For APIs that wrap all responses in an envelope (e.g. {"data": {...}, "meta": {...}}), response unwrapping makes endpoints return just the inner data automatically.

Enabling Response Unwrap

documents:
  - source: https://api.example.com/openapi.json
    output: ./client
    response_unwrap:
      enabled: true
      data_path: data          # default path (default: "data")

Per-Endpoint Overrides

response_unwrap:
  enabled: true
  data_path: data
  endpoints:
    get_user:
      data_path: result.user   # this endpoint uses a different path
    get_raw_data:
      enabled: false           # don't unwrap this endpoint

Response Unwrap Options

Per-Endpoint Options

📖 Using Generated Code

Direct Function Imports

from client import get_user, create_user, list_orders

# Async versions are prefixed with 'async_'
from client import async_get_user, async_create_user, async_list_orders

# Sync
user = get_user(user_id=123)

# Async
import asyncio

async def main():
    user = await async_get_user(user_id=123)

asyncio.run(main())

Module-Specific Imports (with splitting)

from client.users import get_user, create_user
from client.orders import list_orders, get_order

Using the Client Class

from client import Client

client = Client(
    base_url='https://api.example.com',
    timeout=30.0,
    headers={'Authorization': 'Bearer your-token'},
)

user = client.get_user(user_id=123)

async def main():
    user = await client.async_get_user(user_id=123)

Working with Models

from client.models import User, CreateUserRequest

new_user = CreateUserRequest(name='John Doe', email='john@example.com')
user = create_user(body=new_user)
print(user.id, user.email)

🔧 CLI Reference

# Generate from default config (otter.yml, otter.yaml, or pyproject.toml)
otter generate

# Generate from specific config file
otter generate -c my-config.yml

# Tolerate malformed specs (drop unknown/invalid fields with a warning)
otter generate --lenient

# Initialize a new config file
otter init

# Validate configuration
otter validate

🐍 Programmatic API

from otterapi.codegen import Codegen
from otterapi.config import DocumentConfig, PaginationConfig, ExportConfig

config = DocumentConfig(
    source='https://petstore3.swagger.io/api/v3/openapi.json',
    output='./client',
    pagination=PaginationConfig(enabled=True),
    export=ExportConfig(enabled=True, formats=['csv', 'parquet']),
)
Codegen(config).generate()

❗ Error Handling

Generated clients raise a typed exception hierarchy rooted at BaseAPIError:

from my_client import (
    Client, list_users,
    BaseAPIError,        # catches every API error
    ClientError,         # all 4xx
    ServerError,         # all 5xx
    NotFoundError,       # 404
    RateLimitError,      # 429
)

try:
    users = list_users(client=Client())
except NotFoundError as e:
    log.warning('not found: %s', e.detail)
except RateLimitError:
    backoff_and_retry()
except ServerError:
    page_oncall()
except BaseAPIError as e:
    log.error('unexpected %d: %s', e.status_code, e.detail)

Mapped status codes: 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504. Other 4xx/5xx fall through to ClientError/ServerError. Subclass BaseAPIError in your client.py to customize error parsing.

♻️ Regenerating after spec changes

OtterAPI is idempotent for generated files:

• models.py, endpoints.py, _client.py, _pagination.py, _export.py, _dataframe.py are rewritten on every run — never edit them by hand.
• client.py is generated once and left alone — this is your customization seam.

🛠 Development

git clone https://github.com/danplischke/otterapi.git
cd otterapi
uv sync
uv run pytest
uv run pytest --cov=otterapi
uv run ruff format .
uv run ruff check .

📄 License

MIT License — see LICENSE for details.