Generate Go client and server boilerplate from OpenAPI 3 specifications
Nullable typesIt'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:
S.Field == nil)null? (Can be checked with S.Field == nil)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.
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 $refs) now correctly generate code.
There are a few cases that won't be covered, that we'll complete in https://github.com/deepmap/oapi-codegen/issues/1440 but until then, it hopefully should work better.
Thank you to Ejendomstorvet for sponsoring this work.
nullable.Nullable for nullable properties (#1404) @sonasingh46IsMediaTypeJson (#1386) @jamietanna.Required to BindStyledParameterWithLocation and BindStyledParameter (#1315) @renomos.Exit(1) only from main() (#1398) @alexandear.Required to BindStyledParameterWithLocation and BindStyledParameter (#1315) @renomimport-mapping with URLs (#1428) @jamietannaAs 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 |
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/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
pkg/testutil to its own package + remove itSimilar 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.
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.
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.16.1...v1.16.2
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.16.0...v1.16.1
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.
testutil by @jamietanna in https://github.com/deepmap/oapi-codegen/pull/1314
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.15.0...v1.16.0
As flagged in https://github.com/deepmap/oapi-codegen/issues/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.
MiddlewareFunc type for compatibility by @namco1992 in https://github.com/deepmap/oapi-codegen/pull/1134
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.14.0...v1.15.0
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.13.4...v1.14.0
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.13.3...v1.13.4
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.13.2...v1.13.3
Full Changelog: https://github.com/deepmap/oapi-codegen/compare/v1.13.1...v1.13.2