v2.5.0: No more optional pointers (optionally)!

🎉 Notable changes

Begone optional pointers! (optionally)

One of the key things oapi-codegen does is to use an "optional pointer", following idiomatic Go practices, to indicate that a field/type is optional.

This can be tuned on a per-field basis, using the x-go-type-skip-optional-pointer extension, but it can be a bit repetitive, or can be more complex when using an OpenAPI Overlay.

As of oapi-codegen v2.5.0, this can be tuned in two specific ways, via the following Output Options:

• prefer-skip-optional-pointer: a global default that you do not want the "optional pointer" generated. Optional fields will not have an "optional pointer", and will have an omitempty JSON tag
• prefer-skip-optional-pointer-with-omitzero: when used in conjunction with prefer-skip-optional-pointer, any optional fields are generated with an omitzero JSON tag. Requires Go 1.24+

In both cases, there is control on a per-field level to set x-go-type-skip-optional-pointer: false or x-omitzero: false to undo these to field(s).

NOTE

The default is not changing.

We take care to avoid breaking changes so this is, as many changes, an opt-in.

See Globally skipping the "optional pointer" for more details.

Generating omitzero JSON tags, with x-omitzero

Related to the above functionality, it is possible to define the OpenAPI extension x-omitzero on fields to generate the omitzero JSON tag, based on the (now not-so-new) Go 1.24 release.

Thanks to @lzap for the contribution 🚀

NOTE

oapi-codegen does not currently validate the Go version that the module it's generating code for.

This could lead to the omitzero JSON tag being generated, but not being actually usable.

Ensure that you're using a Go 1.24+ version, and that your go directive (for source compatibility) is go 1.24 or i.e. go 1.24.1

Using OpenAPI 3.1 with oapi-codegen

There's some promising behind-the-scenes discussions with may lead to OpenAPI 3.1 support (#373) coming in the not-too-distant future 👀

In the meantime, Jamie (one of the Core Maintainers) has written a blog post about how to use oapi-codegen with OpenAPI 3.1 specs (by downgrading them to OpenAPI 3.0).

Defining your own initialisms

As a means to define your own custom initialisms, it's possible to use the additional-initialisms Output Option.

Thanks @micaelmalta for the contribution 🚀

If your organisation uses a lot of TLAs (Two Letter Acronyms or Three Letter Acronyms) or any other sorts of initialisms, it's handy to be able to configure these yourself.

For instance, if you regularly use the term CSP to refer to Cloud Service Provider, you may want CSP to be used in variable names.

This makes it possible to define i.e.

# ...
output-options:
  name-normalizer: ToCamelCaseWithInitialisms
  additional-initialisms:
    - CSP

NOTE

This only works when the name-normaliser Output Option is set to ToCamelCaseWithInitialisms. An error will occur if you've not configured this correctly.

Minimum version of Go needed for oapi-codegen is now 1.22.5

As part of a couple of updates in #1888 and #1986, we're now requiring Go >= 1.22.5.

Similar to the bump to Go 1.21 in v2.4.0

Notable background work

Since the last oapi-codegen release (all the way in September 2024 🥲) the following big changes towards the project and its ecosystem have been:

• net/http middleware v1.1.0: Better error handling, allow not validating Servers (by configuration) and return an HTTP 405 Method Not Allowed where appropriate
• Jamie posted a look back at the last year
  • Notably also writing up explicitly how the project is currently governed
• runtime: fixes for maps and x-go-type-skip-optional-pointer

🚀 New features and improvements

• feat(client): Add Bytes() to ClientWithResponses responses (#1780) @grongor
• feat(generate): allow generating Server URL boilerplate (#2002) @jamietanna
• feat(output-options): add prefer-skip-optional-pointer-on-container-types (#1979) @jamietanna
• feat(output-options): add prefer-skip-optional-pointer to default to skipping optional pointers (#1694) @aksdb
• feat(output-options): add yaml-tags option (#1798) @deitch
• feat(templates): consolidate logic for whether to use an optional pointer (#1981) @jamietanna
• feat(x-deprecated-reason): add default deprecation message (#2022) @jamietanna
• feat: allow specifying additional-initialisms (#1733) @micaelmalta

🐛 Bug fixes

• Handle leading underscores in property names (#1822) @tobio
• fix(codegen): allow exposing the input spec's operationId (#1945) @jamietanna
• fix(codegen): allow using x-go-type and x-go-type-skip-optional-pointer together (#1957) @Nivl
• fix(output-options): obey prefer-skip-optional-pointer in reference types + add tests for preferskipoptionalpointer (#2021) @jamietanna
• fix(overlay): correctly resolve references after Overlay application (#1825) @jgraeger
• fix(stdhttp): correctly generate root paths (#1953) @jamietanna
• fix: Print the warning message to stderr instead of stdout (#1895) @ignassew
• fix: create directories if they do not exist before writing output file (#1994) @kf-pineapple
• fix: don't generate an "optional pointer" for unknown types (#610) @jens1205

📝 Documentation updates

• docs: add example for how to downgrade OpenAPI 3.1 to 3.0 (#1966) @jamietanna
• Add blog post about using oapi-codegen in a Chi project (#1791) @0xi4o
• Fix broken anchor link for validation middleware section (#2013) @Park-Jongseok
• chore(tests): add additional test case for underscore naming (#1980) @jamietanna
• docs(client): document known issue with duplicated Response models (#2025) @jamietanna
• docs(extensions): correct typo to example (#1999) @i-sevostyanov
• docs(extensions): don't use <details> blocks in <table> (#2019) @jamietanna
• docs(extensions): update example code for x-enumNames (#2000) @jamietanna
• docs(middleware): clarify use of nethttp-middleware for other purposes (#1951) @jamietanna
• docs(sponsors): add Livepeer (#1849) @jamietanna
• docs(sponsors): update Speakeasy URL (#1970) @ndimares
• docs(std-http-server): warn when not using Go 1.22 (#1967) @jamietanna
• docs: add contributors image (#1795) @jamietanna
• docs: add example of using go tool for Go 1.24+ (#1908) @jamietanna
• docs: fix GitHub flavoured markdown (#1934) @MarvinJWendt
• docs: fix typo in flags usage (#1796) @AlekSi
• docs: note the use of a multi-module tools.go (#1788) @jamietanna
• docs: simplify go tool example (#1910) @gaiaz-iusipov

• docs(additional-initialisms): add a usage example (#2026) @jamietanna

👻 Maintenance

• build(labels): add additional labelling (#1848) @jamietanna
• build(labels): add autolabeller for "no main branch please" (#1847) @jamietanna
• build: build against Go 1.24 (#1901) @jamietanna
• build: ensure separately named "Check results" steps (#1850) @jamietanna
• chore(examples): use Go 1.24 with Go 1.24 example (#1925) @jamietanna
• chore(tests): add additional test case for underscore naming (#1980) @jamietanna
• chore: don't use non-GitHub URL for tests (#1926) @jamietanna
• fix(output-options): obey prefer-skip-optional-pointer in reference types + add tests for preferskipoptionalpointer (#2021) @jamietanna

📦 Dependency updates

Sponsors

We would like to thank our sponsors for their support during this release.

New contributors

We had 16 new contributors in this release, thanks folks 🚀

• @0xi4o made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1791
• @AlekSi made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1796
• @tobio made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1822
• @deitch made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1798
• @jgraeger made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1825
• @grongor made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1780
• @micaelmalta made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1733
• @chailandau made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1874
• @MarvinJWendt made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1934
• @ignassew made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1895
• @Nivl made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1957
• @jens1205 made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/610
• @aksdb made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1694
• @i-sevostyanov made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1999
• @Park-Jongseok made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/2013
• @kf-pineapple made their first contribution in https://github.com/oapi-codegen/oapi-codegen/pull/1994