oag

OpenAPI 3.x code generator. TypeScript, React, Python FastAPI.

Download · Report Bug · Examples

Why oag?

Most OpenAPI generators produce bloated output that needs heavy post-processing. oag generates clean, readable code from one config file with one command.

• Parses OpenAPI 3.x specs with full $ref resolution
• Template pack engine: generators are Jinja2 templates, no Rust code needed
• Built-in packs: node-client, react-swr-client, fastapi-server
• First-class SSE support (AsyncGenerator in TS, StreamingResponse in Python)
• Literal-faithful output: a const or single-value enum (a discriminator like type: "message") is always emitted with its value (required in TypeScript, Literal["x"] = "x" in Pydantic), never silently optional or empty
• Packs install locally to .oag/packs/: version them, share them, customize them

Install

curl -fsSL https://raw.githubusercontent.com/urmzd/oag/main/install.sh | sh

The installer verifies the binary against the release’s SHA256SUMS and aborts on a mismatch or when the checksums are missing. SHA256SUMS comes from the same GitHub release over the same HTTPS connection, so it catches a corrupted download or a swapped CDN object, not a compromised release or release token. oag update checks the same checksums (each asset’s .sha256 sidecar, else SHA256SUMS) and refuses an update without them.

Or via cargo:

cargo install oag

Or download binaries from releases.

macOS and Nix: a binary built with cargo install while a Nix shell is active links against that shell’s libiconv (a /nix/store/... path), and fails with dyld: Library not loaded once the store path is gone. oag itself has no Nix configuration. Check with otool -L "$(command -v oag)", and rebuild outside the Nix shell or use the release binary.

Quick Start

oag init -p node-client          # creates oag.yaml, installs pack to .oag/packs/
oag generate                     # generates code

CLI

oag generate [spec]              generate code (spec is optional, defaults to oag.yaml input)
oag generate [spec] --force-scaffold   regenerate scaffold files too
oag validate <spec>              parse an OpenAPI spec and report stats
oag inspect <spec>               dump the parsed IR as JSON
oag init                         create oag.yaml in the current directory
oag init -p <pack> [-p <pack>]   also install packs
oag init --force                 overwrite existing oag.yaml
oag check                        run linters/typecheckers on generated output
oag packs list                   list installed and built-in packs with their digests
oag packs install <path>         install a pack from a local directory
oag packs install --id <id>      install a built-in pack into .oag/packs/ (no network)
oag packs install --id <id>@<ref>  download a pack from GitHub at a pinned tag or commit
oag packs remove <id>            remove a pack
oag completions <shell>          generate shell completions (bash, zsh, fish, powershell, elvish)
oag update                       self-update to latest release
oag version                      print version

The built-in packs are compiled into the oag binary, so oag generate needs no network and the same oag version always produces the same output. A pack in .oag/packs/ (relative to your project root) takes precedence: commit it, gitignore it, or customize it. oag only downloads a pack when you pin a ref explicitly (--id node-client@v0.21.0, or node-client@v0.21.0 as the generator key in oag.yaml), and it never fetches from a branch implicitly. The generated README.md in each output directory records the sha256 of every pack used, so CI can verify what produced the code.

Configuration

oag init creates oag.yaml:

# oag configuration: https://github.com/urmzd/oag
#
# Loaded automatically when running `oag generate`.
# Override the spec with: oag generate other-spec.yaml

input: openapi.yaml

generators:
  node-client:
    output: src/generated

  # react-swr-client:
  #   output: src/generated/react

  # fastapi-server:
  #   output: src/generated/server

# --- Standalone package (pnpm workspace, publishable client) ---
#
# To generate a standalone package instead of drop-in files, add scaffold
# and set source_dir so the package has its own src/ with build tooling:
#
#   node-client:
#     output: packages/api-client
#     source_dir: src
#     scaffold:
#       package_name: "@myorg/api-client"
#       formatter: biome        # biome | false
#       test_runner: vitest     # vitest | false
#       bundler: tsdown         # tsdown | false

# --- Other options ---
#
# naming:
#   strategy: use_operation_id  # or use_route_based
#   aliases:
#     createChatCompletion: chat
#
# Generator options:
#   layout: modular             # bundled | modular | split
#   split_by: tag               # tag | operation | route (only with layout: split)
#   base_url: https://api.example.com
#   no_jsdoc: false

By default, oag generates source files directly into the output directory. No package.json, no build tooling, no extra nesting. Just drop-in files you import from your existing project:

src/generated/
  types.ts
  client.ts
  guards.ts
  sse.ts
  index.ts

Standalone package mode

To generate a publishable package (e.g., for a pnpm workspace), add scaffold and source_dir:

generators:
  node-client:
    output: packages/api-client
    source_dir: src
    scaffold:
      package_name: "@myorg/api-client"

This produces a self-contained package with package.json, tsconfig.json, biome, tsdown, and vitest pre-configured:

packages/api-client/
  package.json
  tsconfig.json
  biome.json
  tsdown.config.ts
  src/
    types.ts
    client.ts
    ...

Scaffold files are write-once: they’re only created if they don’t exist, so your customizations survive regeneration. Use --force-scaffold to reset them.

Layout modes

• modular (default): separate files per concern (types, client, sse, index)
• bundled: everything in a single file
• split: separate files per operation group (by tag, operation, or route)

Template packs

Packs live in .oag/packs/ inside your project. Each pack is a directory with:

• oag.pack.toml: manifest (metadata, type mappings, layouts, formatters)
• templates/: Jinja2 .j2 templates

Packs support inheritance (extends in the manifest). react-swr-client extends node-client. It inherits all base templates and adds React hooks on top.

To customize a built-in pack, install it locally and edit:

oag packs install --id node-client   # copies the built-in pack, no network
# edit .oag/packs/node-client/templates/*.j2
oag generate

Resolution order for a generator key: id@ref (downloaded from GitHub at that ref, cached by ref and digest, with its extends base pinned to the same ref), then .oag/packs/<id>/, then the pack built into the binary. A pack that is neither installed nor built in is an error, never a silent download. A local copy of a built-in pack must have been installed by the running oag version (oag packs install records it in oag.source.toml); an older copy is refused with instructions, unless you pass oag generate --allow-stale-packs.

Upgrading from v0.20

Upgrading from v0.20.x changes generated code in five places. First, clear the packs v0.20 left behind: v0.20 downloaded every missing pack into .oag/packs/, and a local copy of a built-in pack takes precedence over the one built into oag. oag now refuses such a copy (it has no install record, or another oag version installed it) because its templates generate code that does not compile against the new engine and keeps the old retry policy. Delete .oag/packs/<id> for each built-in pack you did not customize; for one you did, run oag packs install --id <id> and reapply your edits. Then regenerate with oag generate --force-scaffold, so scaffolded files such as client.test.ts and package.json follow the new API (they are otherwise written only once). Then:

Fixes that need no migration but remove common workarounds: a $ref enum query parameter serializes as ?state=open; a bodyless 204 next to a default error resolves to void; a discriminator mapping several values to one schema compiles; binary downloads resolve to a real Blob; base64 JSON fields get decode<Schema><Field>() helpers; SSE streams release their connection on early exit and report closed-by-server (or throw SSEStreamClosedError with terminalEvents); SSEEvent is exported; generated classes have no constructor parameter properties.

Examples

See examples/ for working projects:

• petstore: Node + React clients from the Petstore 3.2 spec
• sse-chat: SSE streaming with Node + React hooks
• event-stream: OAS 3.2 SSE events typed by name, base64 JSON payloads, a binary download, a shared discriminator mapping, a $ref enum query parameter, and a 204 next to a default error

Regenerate with just examples.

Architecture

oag-cli  -->  oag-core (engine)  -->  packs: node-client, react-swr-client (extends node-client), fastapi-server

Agent Skill

This repo’s conventions are available as portable agent skills in skills/.

License

Apache-2.0