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-with-omitzero, 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).

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 🚀

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

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

🐛 Bug fixes

• Handle leading underscores in property names (Handle leading underscores in property names #1822) @tobio
• fix(codegen): allow exposing the input spec's operationId (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 (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 (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 (fix(overlay): correctly resolve references after Overlay application #1825) @jgraeger
• fix(stdhttp): correctly generate root paths (fix(stdhttp): correctly generate root paths #1953) @jamietanna
• fix: Print the warning message to stderr instead of stdout (fix: Print the warning message to stderr instead of stdout #1895) @ignassew
• fix: create directories if they do not exist before writing output file (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 (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 ( 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 (Add blog post about using oapi-codegen in a Chi project #1791) @0xi4o
• Fix broken anchor link for validation middleware section (docs: fix broken anchor link for validation middleware section #2013) @Park-Jongseok
• chore(tests): add additional test case for underscore naming (chore(tests): add additional test case for underscore naming #1980) @jamietanna
• docs(client): document known issue with duplicated Response models (docs(client): document known issue with duplicated Response models #2025) @jamietanna
• docs(extensions): correct typo to example (docs(extensions): correct typo to example #1999) @i-sevostyanov
• docs(extensions): don't use <details> blocks in <table> (docs(extensions): don't use <details> blocks in <table> #2019) @jamietanna
• docs(extensions): update example code for x-enumNames (docs(extensions): update example code for x-enumNames #2000) @jamietanna
• docs(middleware): clarify use of nethttp-middleware for other purposes (docs(middleware): clarify use of nethttp-middleware for other purposes #1951) @jamietanna
• docs(sponsors): add Livepeer (docs(sponsors): add Livepeer #1849) @jamietanna
• docs(sponsors): update Speakeasy URL (docs(sponsors): update Speakeasy URL #1970) @ndimares
• docs(std-http-server): warn when not using Go 1.22 (docs(std-http-server): warn when not using Go 1.22 #1967) @jamietanna
• docs: add contributors image (docs: add contributors image #1795) @jamietanna
• docs: add example of using go tool for Go 1.24+ (docs: add example of using go tool for Go 1.24+ #1908) @jamietanna
• docs: fix GitHub flavoured markdown (docs: fix GitHub flavoured markdown #1934) @MarvinJWendt
• docs: fix typo in flags usage (docs: fix typo in flags usage #1796) @AlekSi
• docs: note the use of a multi-module tools.go (docs: note the use of a multi-module tools.go #1788) @jamietanna
• docs: simplify go tool example (docs: simplify go tool example #1910) @gaiaz-iusipov

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

👻 Maintenance

• build(labels): add additional labelling (build(labels): add additional labelling #1848) @jamietanna
• build(labels): add autolabeller for "no main branch please" (build(labels): add autolabeller for "no main branch please" #1847) @jamietanna
• build: build against Go 1.24 (build: build against Go 1.24 #1901) @jamietanna
• build: ensure separately named "Check results" steps (build: ensure separately named "Check results" steps #1850) @jamietanna
• chore(examples): use Go 1.24 with Go 1.24 example (chore(examples): use Go 1.24 with Go 1.24 example #1925) @jamietanna
• chore(tests): add additional test case for underscore naming (chore(tests): add additional test case for underscore naming #1980) @jamietanna
• chore: don't use non-GitHub URL for tests (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 (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 Add blog post about using oapi-codegen in a Chi project #1791
• @AlekSi made their first contribution in docs: fix typo in flags usage #1796
• @tobio made their first contribution in Handle leading underscores in property names #1822
• @deitch made their first contribution in feat(output-options): add yaml-tags option #1798
• @jgraeger made their first contribution in fix(overlay): correctly resolve references after Overlay application #1825
• @grongor made their first contribution in feat(client): Add Bytes() to ClientWithResponses responses #1780
• @micaelmalta made their first contribution in feat: allow specifying additional-initialisms #1733
• @chailandau made their first contribution in docs(sponsors): update speakeasy sponsor graphic #1874
• @MarvinJWendt made their first contribution in docs: fix GitHub flavoured markdown #1934
• @ignassew made their first contribution in fix: Print the warning message to stderr instead of stdout #1895
• @Nivl made their first contribution in fix(codegen): allow using x-go-type and x-go-type-skip-optional-pointer together #1957
• @jens1205 made their first contribution in fix: don't generate an "optional pointer" for unknown types #610
• @aksdb made their first contribution in feat(output-options): add prefer-skip-optional-pointer to default to skipping optional pointers #1694
• @i-sevostyanov made their first contribution in docs(extensions): correct typo to example #1999
• @Park-Jongseok made their first contribution in docs: fix broken anchor link for validation middleware section #2013
• @kf-pineapple made their first contribution in fix: create directories if they do not exist before writing output file #1994