oapi-codegen

oapi-codegen is a command-line tool and library to convert OpenAPI specifications to Go code, be it server-side implementations, API clients, or simply HTTP models.

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

With oapi-codegen, there are a few Key Design Decisions we've made, including:

• idiomatic Go, where possible
• fairly simple generated code, erring on the side of verbose code over complex modular code
• supporting as much of OpenAPI 3.0 and 3.1 as is possible, alongside Go's type system

oapi-codegen is one part of a wider ecosystem, which can be found described in further detail in the oapi-codegen organisation on GitHub.

⚠️ This README may be for the latest development version, which may contain unreleased changes. Please ensure you're looking at the README for the latest release version.

Table of Contents

• Installation
• Action Required: The repository for this project has changed
• Installing
• Pinning to commits
• Usage
• Backwards compatibility
• Features
• What does it look like?
• Key design decisions
• Generating server-side boilerplate
• Supported Servers
• Strict server
• Generating API clients
• With Server URLs
• Duplicate types generated for clients's response object types
• Generating API models
• Splitting large OpenAPI specs across multiple packages (aka "Import Mapping" or "external references")
• Using a single package with multiple OpenAPI specs
• Using multiple packages, with one OpenAPI spec per package
• Modifying the input OpenAPI Specification (with OpenAPI Overlay)
• Generating Nullable types
• OpenAPI extensions
• Request/response validation middleware
• Implementing security
• On the server
  • Deprecated: auth scopes on the request context
• On the client
• Custom code generation
• Local paths
• HTTPS paths
• Inline template
• Using the Go package
• Additional Properties (additionalProperties)
• Implicit additionalProperties: true / no additionalProperties set
• Explicit additionalProperties: true
• additionalProperties as integers
• additionalProperties with an object
• Globally skipping the "optional pointer"
• Changing the names of generated types
• Examples
• Blog posts
• Frequently Asked Questions (FAQs)
• Does oapi-codegen support OpenAPI 3.1?
• How does oapi-codegen handle anyOf, allOf and oneOf?
• How can I ignore parts of the spec I don't care about?
• Should I commit the generated code?
• Should I lint the generated code?
• I've just updated my version of kin-openapi, and now I can't build my code 😠
• Contributors
• Sponsors

Installation

Action Required: The repository for this project has changed

As announced in May 2024, we have moved the project from the Deepmap organization to our own organization, and you will need to update your import paths to pull updates past this point. You need to do a recursive search/replace from github.com/deepmap/oapi-codegen/v2 to github.com/oapi-codegen/oapi-codegen/v2.

[!IMPORTANT] oapi-codegen moved to its new home with the version tag v2.3.0.

If you are using v2.2.0 or below, please install like so:

# for the binary install
go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@v2.2.0

If you are using v2.3.0 or above, please install like so, using the new module import path:

# for the binary install
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

Installing

oapi-codegen requires Go 1.25+ to build and install. Note that the generated code has its own, lower requirements — see Supported Servers.

It is recommended to use go tool support for managing the dependency of oapi-codegen alongside your core application.

To do this, you run go get -tool:

$ go get -tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
# this will then modify your `go.mod`

From there, each invocation of oapi-codegen would be used like so:

//go:generate go tool oapi-codegen -config cfg.yaml ../../api.yaml

Alternatively, you can install it as a binary with:

$ go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
$ oapi-codegen -version

Which then means you can invoke it like so:

//go:generate oapi-codegen --config=config.yaml ../../api.yaml

Pinning to commits

While the project does not (yet) have a defined release cadence, there may be cases where you want to pull in yet-unreleased changes to your codebase.

Therefore, you may want to pin your dependency on oapi-codegen to a given commit hash, rather than a tag.

This is officially recommended for consumers of oapi-codegen, who want features/bug fixes that haven't yet been released.

We aim to keep the default branch ready-to-release so you should be able to safely pin.

To do so, you can run:

# pin to the latest version on the default branch
$ go get github.com/oapi-codegen/oapi-codegen/v2@main
# alternatively, to a commit hash i.e. https://github.com/oapi-codegen/oapi-codegen/commit/71e916c59688a6379b5774dfe5904ec222b9a537
$ go get github.com/oapi-codegen/oapi-codegen/v2@71e916c59688a6379b5774dfe5904ec222b9a537

This will then make a change such as:

diff --git go.mod go.mod
index 44f29a4..436a780 100644
--- go.mod
+++ go.mod
@@ -2,21 +2,20 @@
-require github.com/oapi-codegen/oapi-codegen/v2 v2.1.0
+require github.com/oapi-codegen/oapi-codegen/v2 v2.1.1-0.20240331212514-80f0b978ef16

Usage

oapi-codegen is configured using a YAML configuration file, to simplify the number of flags that users need to remember, and to make reading the go:generate command less daunting. While some command line options are supported, they should be considered deprecated, we just maintain them for backward compatibility, but we're not extending them.

For full details of what is supported, check out the oapi-codegen configuration documentation.

We also have a JSON Schema that can be used by IDEs/editors with the Language Server Protocol (LSP) to perform intelligent suggestions, i.e.:

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/v2.8.1/configuration-schema.json
package: api
# ...

Note that it's recommended to pin to a specific version of the configuration schema, so it matches the version of oapi-codegen you're using. For instance, if you're using Renovate, you can have Renovate automagically update this version for you.

Backwards compatibility

Although we strive to retain backwards compatibility - as a project that's using a stable API per SemVer - there are sometimes opportunities we must take to fix a bug that could cause a breaking change for people relying upon the behaviour.

In this case, we will expose a compatibility option to restore old behaviour.

That all being said, we operate in a little bit of a grey area, since we are a code generator, we support template overrides, and our code can be imported. So this is how we will try to maintain compatibility:

• SemVer mostly applies to generated code. We strive to avoid breaking your code which depends on the generated code. We will provide compatibility flags for major breaking changes.
• A breaking change could happen with either a compilation error (as something has changed in the generated code) or a behaviour change (we generate a slightly different implementation)
• However, if you're using generated code that is "off the beaten path", on a seldom encountered edge case, we'll sometimes decide to make a breaking change to avoid complicating usage or internals.
• [Our pkg/ directory is importable](https://pkg.go.dev/github.com/oapi-codege