Apigen: OpenAPI Python Client Generator

Apigen is a small OpenAPI-to-Python client generator. It reads an OpenAPI 3 JSON spec, builds an intermediate representation, and emits a typed Python client using only the Python standard library.

The generated client includes dataclasses for schemas, endpoint methods, path/query parameters, JSON request bodies, bearer token and API-key hooks, plus a small ApiError wrapper.

Features

• OpenAPI 3 JSON loader.
• Deterministic IR for models and operations.
• Python dataclass model generation.
• Endpoint methods from operationId.
• Path and query parameter support.
• JSON request/response mapping.
• Bearer token and X-API-Key auth hooks.
• Golden tests for generated output.
• Integration test that runs the generated client against a local sample server.

Quick Start

go test ./...
go run ./cmd/apigen generate --spec examples/tiny-store.openapi.json --out client.py
python3 -m py_compile client.py

Inspect a spec:

go run ./cmd/apigen inspect --spec examples/tiny-store.openapi.json

CLI

apigen generate --spec openapi.json --out client.py
apigen inspect  --spec openapi.json
apigen version

Generated Client Example

from client import Client, CreateUserRequest

client = Client("http://127.0.0.1:8080", bearer_token="dev-token")
users = client.list_users(limit=10)
created = client.create_user(CreateUserRequest(email="bob@example.test", display_name="Bob"))

print(users[0].email)
print(created.id)

Sample Server Demo

Generate the client:

go run ./cmd/apigen generate --spec examples/tiny-store.openapi.json --out examples/client.py

Run the sample server:

python3 examples/sample_server.py

In another terminal:

PYTHONPATH=examples python3 examples/smoke_client.py

On Windows with Python Launcher:

py -3 examples\sample_server.py
$env:PYTHONPATH = "examples"
py -3 examples\smoke_client.py

Scope

This MVP intentionally supports a focused subset:

• JSON OpenAPI specs
• components.schemas
• object schemas, primitive fields, arrays and $ref
• JSON request bodies
• JSON 2xx responses
• path and query parameters

It does not store secrets in generated clients. Tokens are passed at runtime via Client(..., bearer_token=...) or api_key=....

Architecture

flowchart LR
  A["OpenAPI JSON"] --> B["schema loader"]
  B --> C["intermediate representation"]
  C --> D["Python backend"]
  D --> E["client.py"]
  E --> F["golden + integration tests"]

Loading

More details are in docs/architecture.md.

License

MIT