oapi-codegen

Battle-tested: This generator is continuously tested against 2,000+ real-world OpenAPI specs, successfully generating and compiling over 20 million lines of Go code. Handles complex specs with circular references, deep nesting, and union types.

Using oapi-codegen allows you to reduce the boilerplate required to create or integrate with services based on OpenAPI 3.x, and instead focus on writing your business logic, and working on the real value-add for your organization.

Features

Code Generation

• Idiomatic Go code - Clean, readable generated code that follows Go conventions
• OpenAPI 3.x support - Comprehensive support for OpenAPI 3.0 and 3.1 specifications
• Flexible output - Single or multiple file output with configurable structure
• Smart pruning - Automatically removes unused types by default (configurable)

Type System

• Union types - Full support for oneOf, anyOf, allOf, and if/then/else with intelligent type merging, runtime.Either[A, B] for two-element unions, and runtime.Conditional[T, E] for conditional schemas
• Additional properties - Handle dynamic fields with map[string]interface{} or custom types
• Validation - Built-in validation using go-playground/validator with Validate() methods on generated types
• Custom extensions - for fine-grained control over code generation

Client Generation

• HTTP client generation - Generate type-safe HTTP clients with customizable timeout and request editors
• Envelope WithResponse clients - Opt-in <Op>WithResponse siblings that return a typed envelope with per-status bodies, typed headers, and the raw *http.Response - useful for operations that legitimately return multiple 2xx statuses or need typed access to response headers
• Streaming responses - Opt-in <Op>Stream siblings for Server-Sent Events and newline-delimited JSON, returning a live runtime.Stream[T] over the per-frame type instead of buffering. An operation declaring both application/json and text/event-stream exposes both shapes
• Custom client types - Wrap generated clients with your own types for additional functionality
• Error mapping - Map response types to implement the error interface automatically

Server Generation

• Complete server scaffolding - Generate service interfaces, HTTP adapters, routers, and server main.go
• 13 framework support - Chi, Echo, Gin, Fiber, std-http, Beego, go-zero, Kratos, GoFrame, Hertz, gorilla-mux, fasthttp, Iris
• Clean architecture - Service interface pattern separates business logic from HTTP handling
• Request/response validation - Optional validation in generated handlers

MCP Server Generation

• MCP (Model Context Protocol) - Generate MCP servers for AI assistant integration
• Tool generation - Each API operation becomes an MCP tool that AI assistants can call
• x-mcp extension - Control tool names, descriptions, and skip operations
• Works with Claude Desktop, Cursor, and other MCP clients

Configuration & Filtering

• YAML-based configuration with JSON schema validation
• Flexible filtering - Include/exclude by paths, tags, operation IDs, webhooks, schema properties, or extensions
• Transitive pruning - Automatically remove schemas that are only referenced by filtered-out properties
• OpenAPI Overlays - Modify specs without editing originals (add extensions, remove paths)
• External file $ref resolution - Split specs across multiple files with relative $ref references (auto-detected from spec path, or set base-path in config)

Programmatic Access

• Runtime package - Public API for working with generated types
• TypeTracker - Internal API for managing type definitions programmatically (for advanced use cases)

Quick Start

# Install
go install github.com/doordash-oss/oapi-codegen-dd/v3/cmd/oapi-codegen@latest

# Generate code from the Petstore example
oapi-codegen https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml > petstore.go

Examples

The examples directory contains useful examples of how to use oapi-codegen.

Why v3?

This project is a fork of oapi-codegen v2, fully reworked to address limitations in the original.

Compatibility

Tested against 2,137 real-world OpenAPI 3.0 specs:

Key Improvements

Migration

If you're migrating from v2, please refer to the migration guide.

License

This project is licensed under the Apache License 2.0.
See LICENSE.txt for details.

Notices

See NOTICE.txt for third-party components and attributions.

Contributor License Agreement (CLA)

Contributions to this project require agreeing to the DoorDash Contributor License Agreement.
See CONTRIBUTOR_LICENSE_AGREEMENT.txt.