additionalProperties)](#additional-properties-additionalproperties)
+ - [Implicit additionalProperties: true / no additionalProperties set](#implicit-additionalproperties-true--no-additionalproperties-set)
+ - [Explicit additionalProperties: true](#explicit-additionalproperties-true)
+ - [additionalProperties as integers](#additionalproperties-as-integers)
+ - [additionalProperties with an object](#additionalproperties-with-an-object)
+- [Globally skipping the "optional pointer"](#globally-skipping-the-optional-pointer)
+- [Changing the names of generated types](#changing-the-names-of-generated-types)
+- [Examples](#examples)
+ - [Blog posts](#blog-posts)
+- [Frequently Asked Questions (FAQs)](#frequently-asked-questions-faqs)
+ - [Does oapi-codegen support OpenAPI 3.1?](#does-oapi-codegen-support-openapi-31)
+ - [How does oapi-codegen handle anyOf, allOf and oneOf?](#how-does-oapi-codegen-handle-anyof-allof-and-oneof)
+ - [How can I ignore parts of the spec I don't care about?](#how-can-i-ignore-parts-of-the-spec-i-dont-care-about)
+ - [Should I commit the generated code?](#should-i-commit-the-generated-code)
+ - [Should I lint 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 😠](#ive-just-updated-my-version-of-kin-openapi-and-now-i-cant-build-my-code-)
+- [Contributors](#contributors)
+- [Sponsors](#sponsors)
+
+
+## Installation
+
+### Action Required: The repository for this project has changed
As announced in [May 2024](https://github.com/oapi-codegen/oapi-codegen/discussions/1605),
-we have moved the project from the deepmap organization to our own organization, and you will need to update your
+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`.
@@ -40,7 +96,7 @@ If you are using `v2.3.0` or above, please install like so, using the new module
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
```
-## Install
+### For Go 1.24+
It is recommended to follow [the `go tool` support available from Go 1.24+](https://www.jvt.me/posts/2025/01/27/go-tools-124/) for managing the dependency of `oapi-codegen` alongside your core application.
@@ -105,9 +161,12 @@ index 44f29a4..436a780 100644
## Usage
-`oapi-codegen` is largely 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.
+`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, it's worth checking out [the GoDoc for `codegen.Configuration`](https://pkg.go.dev/github.com/oapi-codegen/oapi-codegen/v2/pkg/codegen#Configuration).
+For full details of what is supported, check out the [oapi-codegen configuration documentation](docs/configuration.md).
We also have [a JSON Schema](configuration-schema.json) that can be used by IDEs/editors with the Language Server Protocol (LSP) to perform intelligent suggestions, i.e.:
@@ -366,14 +425,15 @@ We can see that this provides the best means to focus on the implementation of t
- Produce an interface that can be satisfied by your implementation, with reduced boilerplate
- Bulk processing and parsing of OpenAPI document in Go
- Resulting output is using Go's `text/template`s, which are user-overridable
-- Attempts to produce Idiomatic Go
-- Single-file output
-- Support multiple OpenAPI files by having a package-per-OpenAPI file
+- Attempts to produce idiomatic Go
+- Support multiple OpenAPI files by having a package per OpenAPI file
- Support of OpenAPI 3.0
- OpenAPI 3.1 support is [awaiting upstream support](https://github.com/oapi-codegen/oapi-codegen/issues/373)
However, we do have an experimental version using a different OpenAPI parser which does support 3.1 and 3.2, which
you can play around with in our [experimental repo](https://github.com/oapi-codegen/oapi-codegen-exp/tree/main/experimental)
- - Note that this does not include OpenAPI 2.0 (aka Swagger)
+ - Note that this does not include OpenAPI 2.0 (aka Swagger). If you have an old Swagger
+ specification, you can use a [converter](https://converter.swagger.io/) before
+ using oapi-codegen.
- Extract parameters from requests, to reduce work required by your implementation
- Implicit `additionalProperties` are ignored by default ([more details](#additional-properties-additionalproperties))
- Prune unused types by default
@@ -382,2423 +442,467 @@ We can see that this provides the best means to focus on the implementation of t
`oapi-codegen` shines by making it fairly straightforward (note that this is a purposeful choice of wording here - we want to avoid words like "easy") to generate the server-side boilerplate for a backend API.
-Below you can find the supported servers, and more information about how to implement a server using them.
+You can find the supported HTTP server backends below, and more information about how to implement a server on top of each router.
To provide you a fully Test Driven Development style test harness to confirm you are following the specification, you could use a tool such as [openapi.tanna.dev/go/validator](https://openapi.tanna.dev/go/validator/), or craft your own.
### Supported Servers
-Right now, we support the following servers, and are supportive of adding new servers, too!
+Right now, we support the following servers, and are supportive of adding new servers, too! Each
+server lists a minimum require Go version to compile the generated code, which may
+be different from that of oapi-codegen itself. While the code may compile on an
+older version of Go, we don't promise that it'll work.
+
+| Server | `generate` flag | Go Version | Documentation |
+| --- | --- |------------| --- |
+| [Chi](https://github.com/go-chi/chi) | `chi-server` | 1.24+ | [Chi documentation](docs/chi-server.md) |
+| [Echo](https://github.com/labstack/echo) | `echo-server` | 1.24+ | [Echo documentation](docs/echo-server.md) |
+| [Echo v5](https://github.com/labstack/echo) | `echo5-server` | 1.24+ | [Echo v5 documentation](docs/echo5-server.md) |
+| [Fiber](https://github.com/gofiber/fiber) | `fiber-server` | 1.24+ | [Fiber documentation](docs/fiber-server.md) |
+| [Gin](https://github.com/gin-gonic/gin) | `gin-server` | 1.24+ | [Gin documentation](docs/gin-server.md) |
+| [gorilla/mux](https://github.com/gorilla/mux) | `gorilla-server` | 1.24+ | [gorilla/mux documentation](docs/gorilla-server.md) |
+| [Iris](https://github.com/kataras/iris) | `iris-server` | 1.24+ | [Iris documentation](docs/iris-server.md) |
+| [1.22+ `net/http`](https://pkg.go.dev/net/http) | `std-http-server` | 1.24+ | [`net/http` documentation](docs/stdhttp-server.md) |
-| -Server - | -
-generate flag to enable code generation
- |
--Required Go Version - | --Example usage - | -
|---|---|---|---|
| - -[Chi](https://github.com/go-chi/chi) - - | -
-chi-server
- |
--1.22+ - | -+### Strict server +`oapi-codegen` also supports generating a server that is much more strict with the contract that the implementer requires, and takes inspiration from server-side code generation for RPC servers. -For a Chi server, you will want a configuration file such as: +This takes the boilerplate reduction from the non-strict servers and adds additional boilerplate reduction, allowing you to make the following changes to your function signatures: -```yaml -# yaml-language-server: ... -package: api -generate: - chi-server: true - models: true -output: gen.go +```diff +-FindPets(w http.ResponseWriter, r *http.Request, params FindPetsParams) ++FindPets(ctx context.Context, request FindPetsRequestObject) (FindPetsResponseObject, error) ``` -To implement this, check out [the Chi docs](#impl-chi). - - | -
| +The strict server has support for: -[Echo](https://github.com/labstack/echo) +- multiple request/response media types and status codes on a given operation +- first-class support for `multipart/form-data` and `application/x-www-form-urlencoded` requests +- returning an [HTTP 500 Internal Server Error](https://http.cat/500), when an `error` is returned from a function +- automagic (un)marshalling of request/responses, and setting `content-type` and HTTP status codes on responses +- binding request values to a struct, a `multipart.Reader` or providing a `io.Reader` - | -
-echo-server
- |
--1.22+ - | -+You can see a little more detail of the generated code in the ["What does it look like"](#what-does-it-look-like-strict) section. -For an Echo server, you will want a configuration file such as: +> [!NOTE] +> To configure the strict server generation, you must specify another server to be generated. For instance: ```yaml -# yaml-language-server: ... +# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json package: api generate: - echo-server: true - models: true -output: gen.go + # NOTE another server must be added! + chi-server: true + strict-server: true +output: server.gen.go ``` -To implement this, check out [the Echo docs](#impl-echo). +> [!NOTE] +> This doesn't include [validation of incoming requests](#requestresponse-validation-middleware). - | -
| +As well as generating the server-side boilerplate, `oapi-codegen` can also generate API clients. -[Fiber](https://github.com/gofiber/fiber) +This aims to be an API client that can be used to interact with the methods of the API, and is perfectly suited for production usage. - | -
-fiber-server
- |
--1.24+ - | -+However, if you were looking for a slightly more SDK-style approach, or a mix of generated tests and/or documentation, this API client may not be for you, and you may want to look at alternate tooling. -For a Fiber server, you will want a configuration file such as: +For instance, given an `api.yaml`: ```yaml -# yaml-language-server: ... -package: api -generate: - fiber-server: true - models: true -output: gen.go +openapi: "3.0.0" +info: + version: 1.0.0 + title: Generate models +paths: + /client: + get: + operationId: getClient + responses: + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/ClientType" + put: + operationId: updateClient + responses: + 400: + content: + application/json: + schema: + type: object + properties: + code: + type: string + required: + - code +components: + schemas: + ClientType: + type: object + required: + - name + properties: + name: + type: string + # NOTE that this is not generated by default because it's not referenced. If you want it, you need to use the following YAML configuration: + # + # output-options: + # skip-prune: true + Unreferenced: + type: object + required: + - id + properties: + id: + type: integer ``` -To implement this, check out [the Fiber docs](#impl-fiber). - - | -
| - -[Gin](https://github.com/gin-gonic/gin) - - | -
-gin-server
- |
--1.22+ - | -- -For a Gin server, you will want a configuration file such as: +And a `cfg.yaml`: ```yaml -# yaml-language-server: ... -package: api +# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json +package: client +output: client.gen.go generate: - gin-server: true models: true -output: gen.go + client: true ``` -To implement this, check out [the Gin docs](#impl-gin). - - | - -
| - -[gorilla/mux](https://github.com/gorilla/mux) - - | -
-gorilla-server
- |
--1.22+ - | -+And a `generate.go`: -For a gorilla/mux server, you will want a configuration file such as: +```go +package client -```yaml -# yaml-language-server: ... -package: api -generate: - gorilla-server: true - models: true -output: gen.go +//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml ``` -To implement this, check out [the gorilla/mux docs](#impl-gorillamux). - - | -
| - -[Iris](https://github.com/kataras/iris) +This would then generate: - | -
-iris-server
- |
--1.22+ - | -+```go +package client -For a Iris server, you will want a configuration file such as: +// ... -```yaml -# yaml-language-server: ... -package: api -generate: - iris-server: true - models: true -output: gen.go -``` +// ClientType defines model for ClientType. +type ClientType struct { + Name string `json:"name"` +} -To implement this, check out [the Iris docs](#impl-iris). +// ... - | -
| + // Doer for performing requests, typically a *http.Client with any + // customized settings, such as certificate chains. + Client HttpRequestDoer -[1.22+ `net/http`](https://pkg.go.dev/net/http) + // A list of callbacks for modifying requests which are generated before sending over + // the network. + RequestEditors []RequestEditorFn +} - | -
-std-http-server
- |
--1.22+ - | -+// ... -To use purely `net/http` (for Go 1.22+), you will want a configuration file such as: +// The interface specification for the client above. +type ClientInterface interface { + // GetClient request + GetClient(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error) -```yaml -# yaml-language-server: ... -package: api -generate: - std-http-server: true - models: true -output: gen.go -``` + // UpdateClient request + UpdateClient(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error) +} -To implement this, check out [the Go 1.22+ `net/http` docs](#impl-stdhttp). +// ... - | -
| -Extension - | --Description - | -
|---|---|
|
-
-`x-go-type` -`x-go-type-import` - - |
--Override the generated type definition (and optionally, add an import from another package) - | -
| - -`x-go-type-skip-optional-pointer` - - | --Do not add a pointer type for optional fields in structs - | -
| - -`x-go-name` - - | --Override the generated name of a field or a type - | -
| - -`x-go-type-name` - - | --Override the generated name of a type - | -
| - -`x-omitempty` - - | --Force the presence of the JSON tag `omitempty` on a field - | -
| - -`x-omitzero` - - | --Force the presence of the JSON tag `omitzero` on a field - | -
| - -`x-go-json-ignore` - - | --When (un)marshaling JSON, ignore field(s) - | -
| - -`x-oapi-codegen-extra-tags` - - | --Generate arbitrary struct tags to fields - | -
| - -`x-enum-varnames` / `x-enumNames` - - | --Override generated variable names for enum constants - | -
| - -`x-deprecated-reason` - - | --Add a GoDoc deprecation warning to a type - | -
| - -`x-order` - - | --Explicitly order struct fields - | -
| - -`x-oapi-codegen-only-honour-go-name` - - | --Only honour the `x-go-name` when generating field names - | -
+# Required: Go package name +package: api + +# What to generate (only one server type at a time) +generate: + chi-server: false + echo-server: false + fiber-server: false + gin-server: false + gorilla-server: false + iris-server: false + std-http-server: false + strict-server: false + client: false + models: false + embedded-spec: false + server-urls: false + +# Backward compatibility settings +compatibility: + old-merge-schemas: false + old-enum-conflicts: false + old-aliasing: false + disable-flatten-additional-properties: false + disable-required-readonly-as-pointer: false + always-prefix-enum-values: false + apply-chi-middleware-first-to-last: false + apply-gorilla-middleware-first-to-last: false + circular-reference-limit: 0 + allow-unexported-struct-field-names: false + preserve-original-operation-id-casing-in-embedded-spec: false + +# Output modification options +output-options: + include-tags: [] + exclude-tags: [] + include-operation-ids: [] + exclude-operation-ids: [] + exclude-schemas: [] + skip-fmt: false + skip-prune: false + name-normalizer: "" + initialism-overrides: false + additional-initialisms: [] + response-type-suffix: "" + client-type-name: "" + nullable-type: false + disable-type-aliases-for-type: [] + resolve-type-name-collisions: false + prefer-skip-optional-pointer: false + prefer-skip-optional-pointer-with-omitzero: false + prefer-skip-optional-pointer-on-container-types: false + type-mapping: + integer: + default: + type: int + formats: + int: { type: int } + int8: { type: int8 } + int16: { type: int16 } + int32: { type: int32 } + int64: { type: int64 } + uint: { type: uint } + uint8: { type: uint8 } + uint16: { type: uint16 } + uint32: { type: uint32 } + uint64: { type: uint64 } + number: + default: + type: float32 + formats: + float: { type: float32 } + double: { type: float64 } + boolean: + default: + type: bool + string: + default: + type: string + formats: + byte: { type: "[]byte" } + email: { type: openapi_types.Email } + date: { type: openapi_types.Date } + date-time: { type: time.Time, import: time } + json: { type: json.RawMessage, import: encoding/json } + uuid: { type: openapi_types.UUID } + binary: { type: openapi_types.File } + yaml-tags: false + client-response-bytes-function: false + user-templates: {} + overlay: + path: "" + strict: true + +# External reference to Go package mapping +import-mapping: {} + +# Additional Go imports +additional-imports: [] ++ +# `package` + +The Go package name for the generated code. This is the only required setting. + +```yaml +package: api +``` + +# `import-mapping` + +Maps external OpenAPI `$ref` paths to Go package import paths. Used when splitting specs across multiple packages. + +```yaml +import-mapping: + common.yaml: github.com/myorg/myproject/api/common + auth.yaml: github.com/myorg/myproject/api/auth +``` + +# `additional-imports` + +Defines additional Go imports to add to the generated code. + +```yaml +additional-imports: + - alias: mylib + package: github.com/myorg/mylib +``` + +Each entry has: +- `package` (required): the Go import path +- `alias` (optional): an import alias + +# Generate options + +These are specified under the `generate` key. Only one server type may be enabled at a time. + +If the `generate` block is omitted entirely, it defaults to generating an Echo server with models and an embedded spec. + +## Server types + +| Setting | Description | +| --- | --- | +| `chi-server` | Generate [Chi](https://github.com/go-chi/chi) server boilerplate | +| `echo-server` | Generate [Echo](https://github.com/labstack/echo) server boilerplate | +| `fiber-server` | Generate [Fiber](https://github.com/gofiber/fiber) server boilerplate | +| `gin-server` | Generate [Gin](https://github.com/gin-gonic/gin) server boilerplate | +| `gorilla-server` | Generate [gorilla/mux](https://github.com/gorilla/mux) server boilerplate | +| `iris-server` | Generate [Iris](https://github.com/kataras/iris) server boilerplate | +| `std-http-server` | Generate Go 1.22+ `net/http` server boilerplate | + +## Other generate flags + +| Setting | Description | +| --- | --- | +| `strict-server` | Generate a strict server wrapper. Must be used alongside one of the server types above. | +| `client` | Generate API client boilerplate | +| `models` | Generate Go type definitions from OpenAPI schemas | +| `embedded-spec` | Embed the OpenAPI spec in the generated code | +| `server-urls` | Generate types for the `servers` definitions' URLs | + +# Compatibility options + +These are specified under the `compatibility` key. They exist to preserve backward-compatible behavior when a bug fix or improvement changes generated output. + +## `old-merge-schemas` + +Reverts to the old behavior for `allOf` schema merging, which inlined each schema within the schema list rather than merging at the schema definition level. See [#531](https://github.com/oapi-codegen/oapi-codegen/issues/531). + +## `old-enum-conflicts` + +Reverts to old behavior for enum type naming that could produce conflicting typenames. See [#549](https://github.com/oapi-codegen/oapi-codegen/issues/549). + +## `old-aliasing` + +Reverts to generating a full Go type definition for every `$ref` instead of using type aliases where possible. See [#549](https://github.com/oapi-codegen/oapi-codegen/issues/549). + +## `disable-flatten-additional-properties` + +When an object contains no members and only an `additionalProperties` specification, it is normally flattened to a map. Set this to `true` to disable that behavior. + +## `disable-required-readonly-as-pointer` + +When an object property is both `required` and `readOnly`, the generated Go model uses a pointer by default. Set this to `true` to generate non-pointer types instead. See [#604](https://github.com/oapi-codegen/oapi-codegen/issues/604). + +## `always-prefix-enum-values` + +When set to `true`, always prefix enum constant variable names with their type name, even when there are no naming conflicts. + +## `apply-chi-middleware-first-to-last` + +Fixes the ordering of Chi middleware so they are chained in the order they are invoked, rather than the historically inverted order. See [#786](https://github.com/oapi-codegen/oapi-codegen/issues/786). + +## `apply-gorilla-middleware-first-to-last` + +Fixes the ordering of gorilla/mux middleware so they are chained in the order they are invoked, rather than the historically inverted order. See [#841](https://github.com/oapi-codegen/oapi-codegen/issues/841). + +## `circular-reference-limit` + +> **Deprecated**: In kin-openapi v0.126.0, the Circular Reference Counter functionality was removed, resolving all references with backtracking instead. + +Allows controlling the limit for circular reference checking in older versions. + +## `allow-unexported-struct-field-names` + +Makes it possible to output structs that have unexported (lowercase) fields. Expected to be used in conjunction with `x-go-name`, `x-oapi-codegen-only-honour-go-name`, and `x-oapi-codegen-extra-tags`. + +Example use case: + +```yaml +# In your OpenAPI spec: +id: + type: string + x-go-name: accountIdentifier + x-oapi-codegen-extra-tags: + json: "-" + x-oapi-codegen-only-honour-go-name: true +``` + +> [!NOTE] +> This can be confusing to users of your OpenAPI specification, who may see a field present and expect to use it in the request/response. + +## `preserve-original-operation-id-casing-in-embedded-spec` + +Ensures that the `operationId` from the source spec is kept intact in the embedded spec output, rather than having the `name-normalizer` applied to it. This keeps the embedded OpenAPI specification in sync with the input specification. + +> [!NOTE] +> This does not impact generated code. If you're using `include-operation-ids` or `exclude-operation-ids`, ensure the `operationId`s used are correct. + +# Output options + +These are specified under the `output-options` key. + +## Filtering + +| Setting | Type | Description | +| --- | --- | --- | +| `include-tags` | `[]string` | Only include operations that have one of these tags. Ignored when empty. | +| `exclude-tags` | `[]string` | Exclude operations that have one of these tags. Ignored when empty. | +| `include-operation-ids` | `[]string` | Only include operations that have one of these operation IDs. Ignored when empty. | +| `exclude-operation-ids` | `[]string` | Exclude operations that have one of these operation IDs. Ignored when empty. | +| `exclude-schemas` | `[]string` | Exclude schemas with the given names from generation. Ignored when empty. | + +## Formatting and pruning + +| Setting | Type | Description | +| --- | --- | --- | +| `skip-fmt` | `bool` | Skip running `goimports` on the generated code | +| `skip-prune` | `bool` | Skip pruning unused components from the generated code | + +## Naming + +| Setting | Type | Description | +| --- | --- | --- | +| `name-normalizer` | `string` | Method used to normalize Go names and types. See [name normalizer values](#name-normalizer-values) below. | +| `initialism-overrides` | `bool` | Whether to use initialism overrides (e.g., `HTTP`, `API`) | +| `additional-initialisms` | `[]string` | Additional initialisms to recognize. Only has effect when `name-normalizer` is set to `ToCamelCaseWithInitialisms`. | +| `response-type-suffix` | `string` | Suffix used for response types | +| `client-type-name` | `string` | Override the default generated client type name | + +### Name normalizer values + +| Value | Example: `getHttpPet` | Example: `OneOf2things` | +| --- | --- | --- | +| (unset / `ToCamelCase`) | `GetHttpPet` | `OneOf2things` | +| `ToCamelCaseWithDigits` | `GetHttpPet` | `OneOf2Things` | +| `ToCamelCaseWithInitialisms` | `GetHTTPPet` | `OneOf2things` | + +## Type generation + +| Setting | Type | Description | +| --- | --- | --- | +| `nullable-type` | `bool` | Generate nullable types for nullable fields | +| `disable-type-aliases-for-type` | `[]string` | OpenAPI types that will not use type aliases. Currently supports: `"array"`. | +| `resolve-type-name-collisions` | `bool` | Automatically rename types that collide across different OpenAPI component sections by appending a suffix (e.g., `Parameter`, `Response`). Without this, codegen errors on duplicate type names. | +| `prefer-skip-optional-pointer` | `bool` | Globally omit the pointer for optional fields/types. Same as adding `x-go-type-skip-optional-pointer` to every field. | +| `prefer-skip-optional-pointer-with-omitzero` | `bool` | Generate the `omitzero` JSON tag for types that would have had an optional pointer. Must be used alongside `prefer-skip-optional-pointer`. A field can set `x-omitzero: false` to opt out. | +| `prefer-skip-optional-pointer-on-container-types` | `bool` | Disable the "optional pointer" for optional container types (slices, maps), avoiding unnecessary `!= nil` checks. | + +## Type mapping + +The `type-mapping` setting allows customizing how OpenAPI type/format combinations map to Go types. User-specified mappings are merged on top of the defaults. + +```yaml +output-options: + type-mapping: + string: + formats: + date-time: + type: mycustomtime.Time + import: github.com/myorg/mycustomtime + integer: + default: + type: int64 +``` + +The structure is: + +```yaml +type-mapping: +