oagen

oagen is a framework for building custom SDK generators from OpenAPI 3.x specifications.

Its core job is narrow:

• parse an OpenAPI spec into a typed intermediate representation (IR)
• let language emitters turn that IR into files
• regenerate the SDK when the spec changes

More advanced workflows, such as preserving the public API of an existing SDK during a migration to generation, is also supported.

Who This Is For

oagen is a fit if you:

• need more control than off-the-shelf generators give you
• want to build or maintain a custom emitter for one or more languages
• care about generated output being idiomatic for a specific SDK style

oagen is probably not a fit if you:

• just want a turnkey SDK generator with batteries included
• do not want to maintain emitter code
• do not need a reusable IR or generation framework

Core Concept

oagen has a small core:

• Parser: OpenAPI 3.x -> ApiSpec IR
• Emitter runtime: ApiSpec -> GeneratedFile[]
• Diffing: compare spec versions and map changes to generated output

Advanced features such as API-surface extraction, compatibility overlays, smoke verification, and live-SDK integration are available, but they are optional. You can ignore them until you need them.

Quickstart

Install the package:

npm install @workos/oagen

Inspect a spec:

oagen parse --spec openapi.yml

Create an emitter project:

oagen init --lang ruby --project ./my-emitter
cd ./my-emitter

Generate files with your emitter:

npm run sdk:generate -- --spec ../openapi.yml --namespace MyService

For the shortest end-to-end setup, see Minimal Quickstart.

The Core API

The default @workos/oagen entrypoint is intentionally focused on the framework core:

import {
  diffSpecs,
  generate,
  generateFiles,
  getEmitter,
  parseSpec,
  planOperation,
  registerEmitter,
  toCamelCase,
  toPascalCase,
  toSnakeCase,
} from "@workos/oagen";
import type {
  ApiSpec,
  Emitter,
  EmitterContext,
  GeneratedFile,
  Model,
  Enum,
  Service,
  OperationPlan,
} from "@workos/oagen";

Advanced compat and verification APIs are available through explicit subpaths:

import {
  buildOverlayLookup,
  patchOverlay,
  registerExtractor,
} from "@workos/oagen/compat";
import { runCompatCheck, runOverlayRetryLoop } from "@workos/oagen/verify";

Building an Emitter

Emitters are pure functions over the IR. They receive typed IR nodes and return GeneratedFile[].

import type { Emitter } from "@workos/oagen";

const myEmitter: Emitter = {
  language: "go",
  generateModels: (models, ctx) => [
    /* ... */
  ],
  generateEnums: (enums, ctx) => [
    /* ... */
  ],
  generateResources: (services, ctx) => [
    /* ... */
  ],
  generateClient: (spec, ctx) => [
    /* ... */
  ],
  generateErrors: () => [],
  generateConfig: () => [],
  generateTests: () => [],
  fileHeader: () => "// Auto-generated by oagen. Do not edit.",
};

Start with:

• Reference Emitter — a working TypeScript emitter with tests against a GitHub-flavored fixture spec
• Minimal Quickstart
• Emitter Contract
• IR Type System Reference

Commands

Command	Purpose
oagen parse	Parse a spec and print IR JSON
oagen init	Scaffold an emitter project
oagen generate	Run a registered emitter
oagen diff	Compare two specs and output a diff report
oagen extract	Advanced: extract an SDK API surface for compat use
oagen verify	Advanced: smoke-test output and run compat checks

See CLI Reference.

Documentation

• Docs Overview
• Core Docs
• Advanced Docs
• Contributor Docs
• Public API Policy
• Versioning and Migration

Advanced Workflows

oagen also includes tooling for a more opinionated migration workflow:

• extract the public API of an existing SDK
• generate a replacement while preserving names and exports
• verify the generated SDK against smoke tests and compatibility checks
• integrate generated files into a live SDK tree

Those workflows are documented separately because they are not required to use the core framework:

• Workflows
• Extractor Contract
• CLI Reference

AI / Plugin Tooling

This repo ships with Claude Code plugin assets and skills for scaffold-and-verify workflows. The framework is usable without any agent tooling.

If you need them, start here:

• Agent Docs
• Emitter Agent Docs
• Testing Agent Docs

Development

npm install
npm run build
npm test
npm run typecheck