Releases: oapi-codegen/oapi-codegen
Updates related to repository move
With this version, oapi-codegen
consolidates all code under github.com/oapi-codegen
. When you install the core tool, please use this new location, github.com/oapi-codegen/oapi-codegen/v2
starting with version v2.3.0
, but continue to use github.com/deepmap/oapi-codegen/v2
with any earlier release.
This release contains changes to import paths, go.mod and the README.
What's Changed
- chore(deps): update middleware dependencies by @jamietanna in #1636
- Rename module post-move by @mromaszewicz in #1643
- Update README by @mromaszewicz in #1646
- Update readme with install instrctions by @mromaszewicz in #1652
Full Changelog: v2.2.0...v2.3.0
v2.2.0: Pure-Go 1.22+ server, documentation overhaul. JSON schema and several bug fixes
Big announcements
In case you've missed it, we've got a few big announcements as maintainers of oapi-codegen
which we'd recommend you read in more depth.
oapi-codegen
is moving to its own org- This is from release v2.3.0, but will be enacted likely before you get a chance to read these release notes, as we want to migrate everything to the same org ASAP
- Creating a more sustainable model for
oapi-codegen
in the future- Please consider looking at sponsoring the maintenance that we do on the project.
We'd also like to thank our sponsors for this release:
🔊 Notable features
The v2.2.0 release was largely focussed on the following big changes, alongside a number of other bug fixes.
Generate a pure Go 1.22+ net/http
server
With Go 1.22+'s enhanced routing, it's now easier than ever to be able to write a pure-Go HTTP service, and thanks to a contribution from @thedadams we now have a std-http-server
, further documented in the Supported Servers section in the README.
Note
Not seeing this working, i.e. seeing a 404 page not found
? Make sure that the go
directive in your project's go.mod
is updated!
In the future we're going to see if we can preemptively warn you if you're not quite set up correctly.
Documentation overhaul
A significant undertaking in this release was to rewrite pretty much every line of documentation we had, as well as introducing a number of additional examples and test cases.
We're excited to hear your feedback on the new structure of the README, the additional docs added, and whether there are any additional examples that may be of use.
JSON Schema configuration
In the spirit of documentation, we now also have a JSON schema which can be found further documented in the Usage section in the README.
This not only gives a separate definition of fields and their meaning, but it can be used with IDEs for autocompletion and validation, allowing for a much better Developer Experience.
kin-openapi upgrade
A few big upgrades have come in kin-openapi, which we use for the underlying OpenAPI parsing and validation, which included a significant breaking change that meant that consumers of oapi-codegen
couldn't upgrade the kin-openapi version until we had made changes in oapi-codegen
.
This has additionally been set up as an FAQ as it's one we commonly get.
🚀 New features and improvements
- feat: add ability to tweak generated names (including use of initialisms) (#1041) @wtertius
- docs: revamp README, add a CONTRIBUTING.md and add a JSON Schema for configuration files (#1485) @jamietanna
- feat: add support for Go 1.22+ net/http routing (#1475) @thedadams
🐛 Bug fixes
- Bug: using x-go-type-name results in missing types (#1397) @jamesphillpotts-fr
- fix: correctly register Fiber middleware (#1615) @jamietanna
- fix: ensure we pre-import
nullable
(#1585) @jamietanna - Prefactor: Changes from #1475 (#1480) @jamietanna
- Ensure docstring comment names are set correctly (#1457) @ConorPKeegan
📝 Documentation updates
- docs(sponsors): add a Sponsors section in README (#1635) @jamietanna
- docs(examples): document how to set up authenticated middleware with a non-
echo
server (#1627) @jamietanna - docs(extensions): add missing
x-go-type-name
docs (#1616) @jamietanna - chore: log warning when using 3.1.x (#1592) @jamietanna
- docs: link to blog post for syncing vendored specs (#1580) @jamietanna
- docs: correct
std-http-server
example (#1576) @sajjanjyothi - docs: revamp README, add a CONTRIBUTING.md and add a JSON Schema for configuration files (#1485) @jamietanna
- docs: update OpenAPI spec links to
main
branch (#1493) @dharsanb - Add Fiber example in README (#1495) @alexandregv
- Prefactor: Changes from #1475 (#1480) @jamietanna
- docs: use relative links to files (#1471) @alexandear
👻 Maintenance
- chore: add missing test case for replaceInitialism (#1624) @alexandear
- Simplify extensions merge in
mergeOpenapiSchemas
(#1424) @Juneezee - chore: log warning when using 3.1.x (#1592) @jamietanna
- refactor: extension variable instead of accessing extensions directly (#1448) @alexandear
- chore(deps): remove dependency on
golang.org/x/lint
(#1588) @jamietanna - docs: revamp README, add a CONTRIBUTING.md and add a JSON Schema for configuration files (#1485) @jamietanna
- chore: add test case for
additionalProperties
bug (#1528) @jamietanna - Prefactor: Build changes for #1475 (#1482) @jamietanna
- Prefactor: Changes from #1475 (#1480) @jamietanna
- Simplify CI build matrix + build against Go 1.22 (#1459) @jamietanna
📦 Dependency updates
16 changes
- fix(deps): update module golang.org/x/tools to v0.21.0 (#1601) @renovate
- fix(deps): update module github.com/getkin/kin-openapi to v0.124.0 (#1532) @renovate
- chore(deps): update module github.com/golangci/golangci-lint to v1.59.0 (#1625) @renovate
- chore(deps): update module github.com/golangci/golangci-lint to v1.58.2 (#1618) @renovate
- chore(deps): update module github.com/golangci/golangci-lint to v1.58.1 (#1603) @renovate
- fix(deps): update module golang.org/x/text to v0.15.0 (#1591) @renovate
- chore(deps): update module github.com/golangci/golangci-lint to v1.58.0 (#1586) @renovate
- fix(deps): update module golang.org/x/tools to v0.20.0 (#1531) @renovate
- fix(deps): update module golang.org/x/tools to v0.19.0 (#1289) @renovate
- fix(deps): update module github.com/getkin/kin-openapi to v0.123.0 (#1431) @renovate
- chore(deps): update module github.com/golangci/golangci-lint to v1.57.2 (#1466) @renovate
- fix(deps): update module github.com/stretchr/testify to v1.9.0 (#1479) @renovate
- chore(deps): update actions/checkout action to v4 (#1290) @renovate
- chore(deps): update actions/setup-go action to v5 (#1375) @renovate
- Update release-drafter/release-drafter action to v6 (#1453) @renovate
- Update module github.com/golangci/golangci-lint to v1.56.1 (#1455) @renovate
v2.1.0: Nullable, external reference improvements, x-order, and many more!
🔊 Notable features
Nullable
types
It's possible that you want to be able to determine whether a field isn't sent, is sent as null
or has a value.
For instance, if you had the following OpenAPI property:
S:
type: object
properties:
Field:
type: string
nullable: true
required: []
The current behaviour in oapi-codegen is to generate:
type S struct {
Field *string `json:"field,omitempty"`
}
However, you lose the ability to understand the three cases, as there's no way to distinguish two of the types from each other:
- is this field not sent? (Can be checked with
S.Field == nil
) - is this field
null
? (Can be checked withS.Field == nil
) - does this field have a value? (
S.Field != nil && *S.Field == "123"
)
Therefore, as requested in #1039, this is now possible to represent with the nullable.Nullable
type from our new library, oapi-codegen/nullable.
If you configure your generator's Output Options as so:
output-options:
nullable-type: true
You will now receive the following output:
type S struct {
Field nullable.Nullable[string] `json:"field,omitempty"`
}
Note that this is opt-in only, due to it being a break in existing signatures and behaviour.
You can find out more about how this works in a blog post with further details.
External references are now handled better
A big change has come in which handling of external references (also called import mappings) is much more resilient and predictable for generated code.
This allows cases where multiple files referencing each other (for instance if you've split your API across multiple files, and join them using $ref
s) now correctly generate code.
There are a few cases that won't be covered, that we'll complete in #1440 but until then, it hopefully should work better.
Thank you to Ejendomstorvet for sponsoring this work.
🚀 New features and improvements
- Add support for x-order extension (#1190) @filintod
- Make arrays use concrete types, not aliases. (#1246) @jkj
- feat: filter by operation ids (#929) @johanneswuerbach
- Allow generating
nullable.Nullable
for nullable properties (#1404) @sonasingh46 - Support media type parameters for
IsMediaTypeJson
(#1386) @jamietanna - Pass
.Required
toBindStyledParameterWithLocation
andBindStyledParameter
(#1315) @renom
🐛 Bug fixes
- Fix: Ensure external refs are propagated to generated code (#1389) @jamietanna
- Fix: Refer to external refs correctly in strict interfaces (#1387) @jamietanna
- refactor(cmd): Use
os.Exit(1)
only frommain()
(#1398) @alexandear - Fix binding for JSON body (#1299) @ShouheiNishi
- Fix: Handle code generation for all multipart content-types (#1385) @ShouheiNishi
- Pass
.Required
toBindStyledParameterWithLocation
andBindStyledParameter
(#1315) @renom
📝 Documentation updates
- Fixes confusing indentation for example code in README.md (#1414) @mtskg
- Document how to use
import-mapping
with URLs (#1428) @jamietanna - Fix typo in README.md (#1351) @eltociear
👻 Maintenance
- Fix typos in flag, tests, doc, and comments (#1287) @alexandear
- add unit tests for go type gen function (#1423) @sonasingh46
- Use non-deprecated function names for oapi-codegen/runtime (#1359) @cimitan
- Onboard to Release Drafter (#1350) @jamietanna
📦 Dependency updates
- Update module github.com/golangci/golangci-lint to v1.55.2 (#1285) @renovate
- feat: bump github.com/getkin/kin-openapi to v0.122.0 (#1364) @chrisgacsal
- Update module golang.org/x/text to v0.14.0 (#1349) @renovate
New Contributors
- @renom made their first contribution in #1315
- @eltociear made their first contribution in #1351
- @chrisgacsal made their first contribution in #1364
- @cimitan made their first contribution in #1359
- @sonasingh46 made their first contribution in #1423
- @mtskg made their first contribution in #1414
- @jkj made their first contribution in #1246
- @filintod made their first contribution in #1190
v2.0.0: Remove deprecated packages
As announced in oapi-codegen v2 is coming, this is a release to perform some cleanup, drastically reducing the dependency graph for users of the library, and migrating to multi-repo middleware and utility packages that can evolve separately to the code generator itself.
There's more details in https://www.jvt.me/posts/2023/10/23/oapi-codegen-v2-decrease/ in the exact benefits ??, but the key metrics you will be interested in seeing are:
Before (v1.13.0) | After (v2.0.0) | |
---|---|---|
Vendored dependency size (MB) | 40 | 6 |
Direct dependencies | 15 | 6 |
Indirect dependencies | 95 | 34 |
Key changes
Full Changelog: v1.16.2...v2.0.0
As a consumer, for the most part you shouldn't have much to do, as if you've been using oapi-codegen v1.15.0 or later, you should be using the new packages.
If you use this as a library or execute it as part of go run
you will need to update module import paths:
-//go:generate go run github.com/deepmap/oapi-codegen/cmd/oapi-codegen --config=config.yaml spec.yaml
+//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml spec.yaml
If you're installing the package via go install
, you'll need to run the following instead:
-go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
+go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest
Move pkg/testutil
to its own package + remove it
Similar to the below changes, we've moved pkg/testutil
to its own package, and removed it from the codebase.
The changes for you as a consumer can be seen here.
This is almost a drop in replacement, the key difference is that there is no longer a RequestBuilder.Go
method, as it is replaced by the RequestBuilder.GoWithHTTPHandler.
Remove deprecated packages:
For the packages:
pkg/chi-middleware
pkg/fiber-middleware
pkg/gin-middleware
pkg/middleware
pkg/runtime
pkg/types
These have been deprecated because they are now hosted as individual modules at https://github.com/oapi-codegen/. Doing so allows for their dependencies to be separated from each other, so your transitive module dependencies decrease. Any code which you generate using v1.15.0 will already refer to these modules in their new location.
v1.16.2: Further improve documentation notices
What's Changed
- Improve deprecation notices by @jamietanna in #1337
Full Changelog: v1.16.1...v1.16.2
v1.16.1: Ensure deprecation comments appear correctly
What's Changed
- Fix: Ensure deprecations are parsed correctly by @jamietanna in #1335
Full Changelog: v1.16.0...v1.16.1
v1.16.0: Reduce runtime dependencies
As part of the final preparation towards the v2 release, this release finalises the use of the new multi-repo packages, and deprecates all internal packages ahead of next week's release removing them.
Key callouts
- Migrate middleware to their own Go modules by @jamietanna in #1257
- Replace + deprecate
testutil
by @jamietanna in #1314
Full Changelog: v1.15.0...v1.16.0
v1.15.0: Remove issues with Go 1.21
Go Toolchain issues
As flagged in #1221, folks using Go 1.21 for their local builds - but maybe not targeting Go 1.21, will have been receiving diffs like:
diff --git a/examples/go.mod b/examples/go.mod
index 4b815bd..929a5b6 100644
--- a/examples/go.mod
+++ b/examples/go.mod
@@ -1,6 +1,8 @@
module github.com/deepmap/oapi-codegen/examples
-go 1.20
+go 1.21
+
+toolchain go1.21.0
This is due to changes in Go 1.21's management of toolchains, and is a side effect of Fiber and Iris targeting Go 1.21.
These dependencies have now been downgraded to requiring 1.20, and we've taken steps as maintainers to reduce the impact in the future, so we should only be targeting the lowest Go version supported by the Go team.
What's Changed
- [Gorilla] update the
MiddlewareFunc
type for compatibility by @namco1992 in #1134 - Re-enable moq's execution by @jamietanna in #1229
- Bump fiber to v2.49.1 by @jamietanna in #1232
- Build project with Go 1.20 and Go 1.21 by @jamietanna in #1251
- Bump Iris to remove Go 1.21 dependency by @jamietanna in #1249
New Contributors
- @namco1992 made their first contribution in #1134
Full Changelog: v1.14.0...v1.15.0
v1.14.0: Iris Support, Go 1.20 requirement, reduction of runtime dependencies, and various other features and fixes
Key callouts
- Update to minimum of Go 1.20 by @jamietanna in #1184
- Work to reduce transitive dependencies by @jamietanna in #1206
- This introduces the first package in github.com/oapi-codegen
What's Changed
- Bump golang.org/x/text from 0.11.0 to 0.12.0 by @dependabot in #1183
- Update to minimum of Go 1.20 by @jamietanna in #1184
- [Codegen] Update lint module for tests by @eugenio-bolt in #1191
- Bump golang.org/x/tools from 0.11.1 to 0.12.0 by @dependabot in #1193
- Use Makefile for linting + increase golangci-lint timeout by @jamietanna in #1198
- Fix: Allow consumers to specify how many circular references are allowed by @jamietanna in #1204
- Allow setting globalState.spec without Generate by @derbylock in #1174
- support staticcheck st1005 by @Hyuga-Tsukui in #1124
- Add Gorilla test case for strict-server by @jamietanna in #1218
- Feat: Add Iris Server Support by @Ns2Kracy in #1088
- Bump github.com/google/uuid from 1.3.0 to 1.3.1 by @dependabot in #1215
- Bump github.com/gofiber/fiber/v2 from 2.48.0 to 2.49.0 by @dependabot in #1216
- Work to reduce transitive dependencies by @jamietanna in #1206
- Override local parameters to global parameters by @ShouheiNishi in #1181
- Fix 'cannot define new methods on non-local type' error by @ShouheiNishi in #1185
- Fix enum in anyOf by @ShouheiNishi in #1207
- Fix reference of multipart response by @ShouheiNishi in #1213
- Fix for multiple JSON media type by @ShouheiNishi in #1210
- Allow merging of schemas with additionalProperties by @ShouheiNishi in #1220
- feat: set retrieve timeout for getting the template text from remote by @alexandear in #1170
New Contributors
- @eugenio-bolt made their first contribution in #1191
- @derbylock made their first contribution in #1174
- @Hyuga-Tsukui made their first contribution in #1124
- @Ns2Kracy made their first contribution in #1088
Full Changelog: v1.13.4...v1.14.0
v1.13.4
What's Changed
- Fix: Generate models for all JSON media types by @jamietanna in #1177
Full Changelog: v1.13.3...v1.13.4