openapi-yagen logo

Yet another OpenAPI generator (openapi-yagen)

Main features:

a small generator core written in C++
specific generators are written in JavaScript with support for ES2023 features (QuickJS) and Inja templates (like Jinja)
extending templates with additional functions defined in JS
possibility to extend existing generators by overriding some files from a specified directory
post-processing of output files using custom tools (code formatters, linters, checkers...)
using generators available via HTTP/S (directly from GitHub, or other sources). The curl tool is required.
understands OpenAPI 3.0, 3.1, 3.2, and Swagger 2.0, converting between them automatically so a generator only needs to be written against one 3.x version (see convert below, and generator-format.md)

Installation

Statically-linked binaries are published on the releases page: openapi-yagen for Linux x86_64, openapi-yagen-linux-arm64 for Linux arm64, and openapi-yagen-macos (a universal binary - runs on both Intel and Apple Silicon Macs). Install one to ~/.local/bin - the standard per-user executable location (see file-hierarchy(7)), already on PATH on most modern distributions - no root/sudo needed:

mkdir -p ~/.local/bin && curl -L https://github.com/openapi-yagen/openapi-yagen/releases/latest/download/openapi-yagen -o ~/.local/bin/openapi-yagen && chmod +x ~/.local/bin/openapi-yagen

If ~/.local/bin isn't already on your PATH, add this to your shell's startup file (e.g. ~/.bashrc, ~/.zshrc) and restart your shell:

export PATH="$HOME/.local/bin:$PATH"

macOS

Grab the universal binary instead, and clear its quarantine flag - it isn't code-signed or notarized (no Apple Developer account behind this project), so Gatekeeper otherwise refuses to run it:

mkdir -p ~/.local/bin && curl -L https://github.com/openapi-yagen/openapi-yagen/releases/latest/download/openapi-yagen-macos -o ~/.local/bin/openapi-yagen && chmod +x ~/.local/bin/openapi-yagen && xattr -d com.apple.quarantine ~/.local/bin/openapi-yagen

Unlike on Linux, ~/.local/bin is never on PATH by default on macOS - don't skip the export PATH step above (/usr/local/bin, the one macOS location that is on PATH out of the box, is normally root-owned and needs sudo to write to, unless Homebrew already claimed it).

Or skip both the quarantine step and the PATH setup with the Docker image below.

Docker

A runtime image is published to the GitHub Container Registry as ghcr.io/openapi-yagen/openapi-yagen, for linux/amd64 and linux/arm64 - the latter runs natively (no emulation) on Apple Silicon under Docker Desktop, making this the easiest route on macOS: no Gatekeeper quarantine step, and no local build toolchain either. Mount the directory holding your spec (and any --override-dir/generator files) as /workspace, its working directory:

docker run --rm -v "$PWD":/workspace ghcr.io/openapi-yagen/openapi-yagen \
  generate openapi.yaml -g builtin:kotlin_ktor_client -o out

Every subcommand below (generate, convert, list-generators, extract, info) works the same way - append it and its options after the image name exactly as you would after the openapi-yagen binary itself. -g/--override-dir/-o/spec-file paths are resolved inside the container, so keep them relative to the directory you mounted. Loading a generator from an HTTP(S) URL (-g https://...) works too - the image bundles curl for that.

An alias makes it behave like a locally installed binary for the rest of a shell session:

alias openapi-yagen='docker run --rm -v "$PWD":/workspace ghcr.io/openapi-yagen/openapi-yagen'

CLI reference

Supported CLI root options and subcommands:

Usage: ./openapi-yagen [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help                   Print this help message and exit
  -v,--version                Print version and exit

Subcommands:
  generate, g                 Generate sources from openapi specification
  convert, c                  Convert an OpenAPI spec from one version to another
  list-generators, l          List built-in generators bundled with this binary (use with -g builtin:<name>)
  extract, e                  Extract a built-in generator's files to a directory, e.g. to customize it further without starting from scratch
  info, i                     Show a generator's metadata: name, description, OpenAPI version, and declared variables

Generate subcommand

Generate sources from openapi specification
Usage: ./openapi-yagen generate [OPTIONS] [spec-file]

Positionals:
  spec-file TEXT [openapi.yaml] 
                              Specification file

Options:
  -h,--help                   Print this help message and exit
  --override-dir TEXT         Directory with overridden generator files
  -o,--out-dir TEXT [.]       Output directory for generated code
  -g,--generator TEXT REQUIRED
                              Path to generator. It can be a directory, zip archive, HTTP URL, or a built-in generator (builtin:<name> - see the list-generators command)
  -p,--post-process TEXT ...  Post process file with specified tool for extension
  -c,--clear                  Clear output directory before generating
  -v,--var TEXT ...           Set variable. Syntax is: -v (var_name)=(var_value)
  -t,--tags TEXT ...          Only generate operations/models tagged with one of these tags (default: generate everything)
  --header TEXT               Override the auto-generated "do not edit" header text prepended to every generated file (default: names the generator; wrapped in whichever comment syntax the file's own extension/generator.yml commentStyle resolves to)
  --no-header                 Disable the auto-generated "do not edit" header entirely

Auto-generated file headers

Every file written via renderTemplate/copyFile (see generator-format.md) gets a "do not edit" header prepended automatically, wrapped in whatever comment syntax that file's own extension uses (# for .rb/.py/.yml, // for .kt/.go/.ts/.h/..., and so on - see lib/generator/file_header.cpp for the full table). An extension the table doesn't recognize (e.g. a hypothetical .json output, which has no comment syntax at all) is left untouched rather than corrupted with a guess. renderTemplateToString's output never gets one, since it's an in-memory fragment (e.g. for a {% include %}-style partial), not a real output file.

The default header names the specific generator that produced the file:

// Code generated by openapi-yagen (kotlin_ktor_server). DO NOT EDIT.
// https://openapi-yagen.github.io

--header "<text>" replaces the message itself (still auto-wrapped in the resolved comment syntax); --no-header disables the header entirely for that run. A generator can also override which comment style the engine picks for its own output, regardless of extension, via generator.yml's commentStyle field (see generator-format.md) - useful if the built-in extension table guesses wrong for an unusual output format.

Clearing the output directory

-c/--clear deletes everything inside --out-dir before generating; without it existing files are kept and only overwritten. As a safeguard, clearing is refused when the output directory is the current directory (the default -o .) or one of its parents - point --out-dir at a dedicated directory for generated code.

Post-processing generated files

-p/--post-process <spec> runs an external command on each generated file, keyed by extension:

-p "ts:prettier --write %file%"

%file% is replaced with the generated file's path. The ext1,ext2: prefix is optional - a -p value with no prefix (just a bare command) runs on every generated file, regardless of extension. Pass -p more than once to chain multiple tools (e.g. one for .kt files, a different one for everything else).

Filtering by tags

-t/--tags <tag>... restricts generation to a subset of the spec's OpenAPI tags. With no -t flag (the default), everything in the spec is generated, unchanged from before this option existed.

openapi-yagen generate openapi.yaml -g builtin:kotlin_ktor_client -o out -t pets -t orders

An operation is kept if it declares any of the given tags (an operation with several tags needs only one to match); an untagged operation is dropped as soon as -t is used at all. This is an engine-level filter, applied before the spec ever reaches the generator's JavaScript: a generator doesn't need to know tag filtering exists to support it. Filtering happens in three steps:

Operations - only matching operations survive, in paths and webhooks alike; a path left with none of its operations remaining is dropped entirely.
Models - components.schemas (and parameters/requestBodies/responses/headers) are pruned down to whatever's still reachable from a surviving operation's parameters, request body, or responses (following $refs, properties, items, allOf/oneOf/anyOf, and so on) - a model only ever used by a filtered-out operation is dropped along with it; one used by both a surviving and a filtered-out operation is kept.
The document's own tags: list is trimmed to the tags actually passed to -t.

Convert subcommand

Convert an OpenAPI spec from one version to another
Usage: ./openapi-yagen convert [OPTIONS] spec-file

Positionals:
  spec-file TEXT REQUIRED     Specification file to convert

Options:
  -h,--help                   Print this help message and exit
  --from TEXT                 Source OpenAPI version (e.g. 2.0, 3.0, 3.1, 3.2) - auto-detected from the spec's own "openapi"/"swagger" field if omitted
  --to TEXT REQUIRED          Target OpenAPI version (e.g. 2.0, 3.0, 3.1, 3.2)
  -o,--out TEXT REQUIRED      Output file path
  --format TEXT               Output format: "yaml" or "json" - inferred from --out's extension if omitted

openapi-yagen convert openapi-3.1.yaml --to 3.0 -o openapi-3.0.yaml

List-generators subcommand

List built-in generators bundled with this binary (use with -g builtin:<name>)
Usage: ./openapi-yagen list-generators [OPTIONS]

Options:
  -h,--help                   Print this help message and exit
  -d,--describe               Also print each generator's description

Extract subcommand

Extract a built-in generator's files to a directory, e.g. to customize it further without starting from scratch
Usage: ./openapi-yagen extract [OPTIONS] name

Positionals:
  name TEXT REQUIRED          Built-in generator name, with or without a "builtin:" prefix (see the list-generators command)

Options:
  -h,--help                   Print this help message and exit
  -o,--out-dir TEXT REQUIRED  Output directory

Info subcommand

Show a generator's metadata: name, description, OpenAPI version, and declared variables
Usage: ./openapi-yagen info [OPTIONS] generator

Positionals:
  generator TEXT REQUIRED     Path to generator. It can be a directory, zip archive, HTTP URL, or a built-in generator (builtin:<name> - see the list-generators command)

Options:
  -h,--help                   Print this help message and exit

openapi-yagen info builtin:kotlin_ktor_client

This is the same version conversion generate runs automatically when a spec's version doesn't match a generator's declared openApiVersion (see generator-format.md), exposed as a standalone tool - useful to inspect what a spec looks like in another version, or to pin a spec to one version before checking it in. It's scoped to the constructs the engine itself models (see the same doc section) rather than a fully lossless converter for every possible spec field.

The output's top-level keys (openapi/info/paths/... or swagger/info/host/... for a 2.0 target) are written in the specification's own documented order, not alphabetical - nested objects still come out alphabetical. String values that would otherwise be ambiguous when read back (a response status code like 200, or a string that happens to look like a bool/float/null, e.g. "true"/"1.5") are always quoted, so they round-trip as strings rather than being silently misread as a different YAML type by another tool.

Examples

Running a generator directly from GitHub

-g also accepts an HTTP/S URL pointing at a generator's source folder, so you can run a generator straight from GitHub without cloning it. openapi-yagen fetches the generator's files (generator.yml, scripts, templates) over HTTP/S as it needs them, so the URL must point at the raw folder contents (curl is required). For example, using this repo's own sample_cpp_models_generator:

openapi-yagen generate openapi.yaml \
    -g https://raw.githubusercontent.com/openapi-yagen/openapi-yagen/master/generators/sample_cpp_models_generator/src \
    -o out

Using a built-in generator

A handful of the generators in generators/ are embedded directly into the openapi-yagen binary at build time, so they work offline with no local checkout, zip, or network access:

openapi-yagen list-generators
openapi-yagen generate openapi.yaml -g builtin:kotlin_ktor_client -o out -v packageName=com.example.petstore

To fork a built-in generator and customize it, extract its files to a directory first:

openapi-yagen extract kotlin_ktor_client -o my-kotlin-client-generator

Writing a generator

See docs/ for the full generator-writing documentation: a step-by-step tutorial building a small generator from scratch, the generator format (folder layout, generator.yml), the JavaScript API (globals, built-in functions), and templating (Inja syntax, calling functions from templates).

Generators

Generators are located in the generators folder. See generators/README.md for the full list - which ones are built into the openapi-yagen binary itself (usable via -g builtin:<name>, see "Using a built-in generator" above) and which need -g pointed at a directory/zip/URL - plus a link to each generator's own documentation.

Development

The project is a CMake + Conan 2 C++20 codebase (core in lib/, CLI in cli/, tests in test/). See AGENTS.md and docs/develop/ for build/test commands, project architecture, and coding conventions - it's the entry point for working on the openapi-yagen engine itself (as opposed to writing a generator, which docs/ covers).

Installation​

macOS​

Docker​

CLI reference​

Generate subcommand​

Auto-generated file headers​

Clearing the output directory​

Post-processing generated files​

Filtering by tags​

Convert subcommand​

List-generators subcommand​

Extract subcommand​

Info subcommand​

Examples​

Running a generator directly from GitHub​

Using a built-in generator​

Writing a generator​

Generators​

Development​

TODO​