OpenAPI Generation

Speakeasy's Go-based generator for producing idiomatic SDKs, Terraform providers, MCP servers, Postman collections, and developer tooling from OpenAPI documents.

Development setup  //  Architecture  //  Command reference  //  Testing guide  //  Contributing  //  Speakeasy CLI

Generate from OpenAPI

This repository is the development home for the generator and its templates. For normal end-user SDK generation, use the Speakeasy CLI. To develop the generator or a target template directly, generate from an OpenAPI document:

go run ./cmd/generate/main.go \
  -s ./tests/specs/basic-http.yaml \
  -o /tmp/generated-sdk \
  -l go \
  --skip-compile

The first run creates .speakeasy/gen.yaml in the output directory with default target configuration. Remove --skip-compile when the generated target's compiler and package tooling are installed. See the command reference for generator, validation, regeneration, and test commands.

Supported targets

The generator supports 12 primary targets:

Target templates live in templates/templates/<target>, with generation and test configuration in tests/config/<variant>/<target>/. OpenAPI 3.0 and 3.1 are supported. The generator also handles selected OpenAPI 3.2 constructs, but OpenAPI 3.2 is not yet supported as a complete document version.

Develop locally

Install Go 1.26.2, Node.js and npm, Docker, and the tooling required by the targets you plan to test. The full setup guide covers target-specific runtimes and local test services:

# Install the repository's documented prerequisites first.
# See SETUP.md for target-specific toolchains.

# Build the generator and validator with the initial mise task.
mise run build

# Run the core contributor checks through mise.
mise run test:generator
mise run test:validate
mise run lint

# Generate and test one target against the primary test variant.
TARGET=primary make test-go

# Check one target's TypeScript templates.
make check-template-go

mise tasks are being introduced incrementally. Use make for target- and variant-specific commands that do not yet have a documented mise equivalent; nested template and zSDKs Makefiles remain supported for their existing consumers.

SDK tests start local httpbin and speakeasy-api-test-service containers automatically. If you change services/speakeasy-api-test-service/, run mise run services:restart before rerunning SDK tests. For command details and common local failures, read the testing guide, command reference, and troubleshooting guide.

How the generator is organised

The generation flow is:

1. Parse and validate the OpenAPI document.
2. Build an SDK-oriented abstract syntax tree (AST).
3. Load the target's templates and TypeScript helpers.
4. Render, format, and optionally compile the generated output.

Read Architecture for the full generation flow and Generator–Target Interface for the TypeScript target contract.

Test generated output

• Add generally applicable OpenAPI coverage with a documented fragment in tests/specs/fragments/.
• Use an overlay only for behavior that is genuinely target- or variant-specific.
• Add runtime coverage under templates/templates/<target>/tests/ when generated behavior needs it.
• Regenerate the relevant zSDKs/ review SDK when a template change affects tracked output.

The repository's snapshot companion is intentionally private. Public pull requests receive only public-safe aggregate snapshot status; snapshot execution must never expose customer inputs, private paths, or private logs.

Telemetry

The generator records usage telemetry for telemetry-eligible generation contexts. To disable it before running the generator:

export SPEAKEASY_DISABLE_TELEMETRY=true

The current implementation records selected target and template, success or failure, operating system and architecture, generator and CLI version, run location, configuration and feature flags, and .speakeasy/gen.yaml ignore rule use. When available, it can also include document- or configuration-derived metadata such as server URL, support contact details, document title, OpenAPI version, customer or workspace identifiers, validation warnings, and validation errors. It does not change an OpenAPI document or generated output.

This disclosure reflects internal/analytics/analytics.go. Review document content before generating if telemetry remains enabled; direct-mode telemetry minimisation is tracked separately from this README update.

Licensing generated output

The repository is licensed under AGPL-3.0. Direct generator use defaults generated output to AGPL-3.0-only and emits a generated LICENSE and NOTICE for Speakeasy-authored material. That notice does not determine the license of content derived solely from the OpenAPI document supplied for generation.

The legal commercial exception, output-composition model, trademark policy, and contribution/relicensing terms are separate work still requiring approved policy text. Nothing in this README grants commercial rights or changes the license of a user's OpenAPI-derived content.

Contributing

Read CONTRIBUTING.md before opening a pull request. Keep a pull request focused, describe generated-output impact, and run the smallest relevant checks first. Never include credentials, customer documents, private repository URLs, private filesystem paths, or unredacted logs in an issue, pull request, fixture, or commit message.

The public security, Code of Conduct, support, CLA/relicensing, trademark, and enforcement routes require approved policy text and will be added separately.