openapi-generator

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0

README

OpenAPI Generator

A Go implementation of the OpenAPI Generator inspired by the original Java-based project.

Why

I ran into issues with Java dependencies and performance in large projects, and many issues stay unresolved in the repository for a long time. I want to build something simpler, easier to maintain, and portable as a single binary with minimal dependencies.

Features

  • Single binary for easy installation and use
  • Fast generation times without JVM overhead
  • Load specs from local files or remote URLs
  • Command-line interface compatible with the original OpenAPI Generator
  • Supports OpenAPI 3.x and Swagger 2.0 specifications, JSON or YAML (auto-converts 2.0 -> 3.x); a 3.1 null member of anyOf/oneOf, a type list with null, a const and a contentMediaType binary string read as their 3.0 forms, as the upstream normalizer's defaults do; 3.2's itemSchema of a streamed response is accepted in a 3.1 document, as FastAPI writes it

Installation

curl -fsSL https://raw.githubusercontent.com/xseman/openapi-generator/master/install.sh | sh

The script downloads the release binary for this platform, checks it against the release's CHECKSUMS.txt and puts it in ~/.local/bin. OPENAPI_GENERATOR_VERSION pins a release, OPENAPI_GENERATOR_INSTALL_DIR changes where it lands. Later, openapi-generator update installs the newest release over the binary the same way.

Windows: download openapi-generator-windows-amd64.exe (or arm64) from the latest release and put it on your PATH; openapi-generator update works there too.

From Source

go install github.com/xseman/openapi-generator/cmd/openapi-generator@latest

Templates

Client

Server

  • (Coming soon)

Usage

openapi-generator generate \
    -i openapi.yaml \
    -g <template> \
    -o ./generated \
    -p key=value \
    -c config.yaml \
    --verbose

Validate a spec without generating code (exits with status 1 on errors; --recommend also lists unused models):

openapi-generator validate -i openapi.yaml --recommend

CLI Options

generate

Option Short Description
--input-spec -i Location of the OpenAPI spec (file or URL)
--generator-name -g typescript-fetch, dart-fetch, go-fetch
--output -o Output directory
--config -c Configuration file (JSON/YAML)
--template-dir -t Custom template directory
--additional-properties -p key=value generator options, a=1,b=2 or repeated
--skip-validate-spec Skip OpenAPI spec validation
--verbose -v Enable verbose output

validate

Option Short Description
--input-spec -i Location of the OpenAPI spec (file or URL)
--recommend Also report recommendations (e.g. unused models)

Note: For generator-specific options, see the template documentation (e.g., typescript-fetch options).

Development

Building and Testing

make build              # bin/openapi-generator
make test               # go vet + go test -race ./...
make lint               # golangci-lint, config in .golangci.yml
make fmt                # gofumpt
make cover              # coverage report
make regress REF=master # diff generated output against a git ref

AGENTS.md maps the packages and states the conventions, for people and agents alike.

Manual Testing

# Generate from a spec
./bin/openapi-generator generate \
    -i petstore.yaml \
    -g typescript-fetch \
    -o ./out

# List available generators
./bin/openapi-generator list

# Show config options for a generator
./bin/openapi-generator config-help typescript-fetch

CI/CD

This project includes a comprehensive CI/CD pipeline:

  • Quality Checks: Automated testing, linting (golangci-lint), and builds on every push/PR
  • Coverage Reports: Test coverage reports posted as comments on pull requests
  • Automated Releases: Release-please based releases with multi-platform binary builds
  • Platform Support: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64)
  • Package Formats: .deb and .rpm packages for Linux distributions

Architecture

Core Components

Component Package Description
Parser internal/parser Parses OpenAPI 2.0/3.x specs using kin-openapi
Codegen internal/codegen Data structures mirroring Java's CodegenModel
Generator internal/generator Generator interface and implementations
Template internal/template Mustache template engine with lambdas
Config internal/config Configuration structs for generators

Generation Pipeline

%%{init: {'theme': 'neutral' } }%%
sequenceDiagram
    participant CLI
    participant Parser
    participant Config
    participant Codegen
    participant Templates

    CLI->>Parser: Load Spec (YAML/JSON)
    Parser-->>Parser: Convert Swagger 2.0 to OpenAPI 3.x
    Parser-->>Parser: Normalize 3.1 null and binary schemas
    Parser-->>CLI: Parsed Spec

    CLI->>Config: Merge CLI + File Config
    Config-->>CLI: Resolved Options

    CLI->>Codegen: Transform to CodegenModels
    Codegen-->>Codegen: Map Types & Properties
    Codegen-->>Codegen: Extract Operations
    Codegen-->>CLI: Codegen Models

    CLI->>Templates: Render API Classes
    Templates-->>CLI: Generated API Files

    CLI->>Templates: Render Models
    Templates-->>CLI: Generated Model Files

    CLI->>Templates: Render Supporting Files
    Templates-->>CLI: Runtime & Configuration Files

Directories

Path Synopsis
cmd
openapi-generator command
Package main provides the CLI for the OpenAPI Generator Go implementation.
Package main provides the CLI for the OpenAPI Generator Go implementation.
internal
codegen
Package codegen provides data structures for code generation from OpenAPI specs.
Package codegen provides data structures for code generation from OpenAPI specs.
config
Package config provides configuration structures for code generators.
Package config provides configuration structures for code generators.
gen
Package gen implements the OpenAPI Generator generation pipeline: it parses an OpenAPI spec, assembles codegen models/operations, renders them through the generator's Mustache templates, and writes the resulting files (plus per-folder index files and .openapi-generator metadata) to disk.
Package gen implements the OpenAPI Generator generation pipeline: it parses an OpenAPI spec, assembles codegen models/operations, renders them through the generator's Mustache templates, and writes the resulting files (plus per-folder index files and .openapi-generator metadata) to disk.
generator
Package generator provides the base interfaces and types for code generators.
Package generator provides the base interfaces and types for code generators.
generator/dart
Package dart provides Dart-specific code generation utilities.
Package dart provides Dart-specific code generation utilities.
generator/golang
Package golang provides the Go code generator; the name is golang because go is a keyword.
Package golang provides the Go code generator; the name is golang because go is a keyword.
generator/typescript
Package typescript provides TypeScript-specific code generation utilities.
Package typescript provides TypeScript-specific code generation utilities.
parser
Package parser provides OpenAPI specification parsing functionality.
Package parser provides OpenAPI specification parsing functionality.
template
Package template provides Mustache template rendering functionality.
Package template provides Mustache template rendering functionality.
update
Package update checks GitHub for a newer openapi-generator and replaces this binary with it.
Package update checks GitHub for a newer openapi-generator and replaces this binary with it.
Package templates provides embedded template files for code generation.
Package templates provides embedded template files for code generation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL