Skip to content

Releases: oapi-codegen/oapi-codegen

Updates related to repository move

06 Jun 21:00
@mromaszewicz mromaszewicz
v2.3.0
43365ff
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
Updates related to repository move Latest
Latest

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

Full Changelog: v2.2.0...v2.3.0

Contributors

jamietanna and mromaszewicz
Assets 2

v2.2.0: Pure-Go 1.22+ server, documentation overhaul. JSON schema and several bug fixes

04 Jun 06:15
@github-actions github-actions
v2.2.0
b660585
Compare
Choose a tag to compare
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.

We'd also like to thank our sponsors for this release:

DevZero logo

🔊 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

📝 Documentation updates

👻 Maintenance

📦 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

Contributors

renovate, alexandear, and 9 other contributors
Assets 2

v2.1.0: Nullable, external reference improvements, x-order, and many more!

25 Jan 15:02
@github-actions github-actions
v2.1.0
ad5eada
Compare
Choose a tag to compare
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 with S.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 $refs) 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

🐛 Bug fixes

📝 Documentation updates

👻 Maintenance

📦 Dependency updates

New Contributors

Contributors

jkj, johanneswuerbach, and 11 other contributors
Assets 2
0 Join discussion

v2.0.0: Remove deprecated packages

31 Oct 20:13
@jamietanna jamietanna
v2.0.0
ba76f6c
Compare
Choose a tag to compare
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.

Assets 2
0 Join discussion

v1.16.2: Further improve documentation notices

24 Oct 12:47
@jamietanna jamietanna
v1.16.2
5d2cd60
Compare
Choose a tag to compare
v1.16.2: Further improve documentation notices

What's Changed

Full Changelog: v1.16.1...v1.16.2

Contributors

jamietanna
Assets 2

v1.16.1: Ensure deprecation comments appear correctly

23 Oct 16:30
@jamietanna jamietanna
v1.16.1
eb5e119
Compare
Choose a tag to compare
v1.16.1: Ensure deprecation comments appear correctly

What's Changed

Full Changelog: v1.16.0...v1.16.1

Contributors

jamietanna
Assets 2

v1.16.0: Reduce runtime dependencies

23 Oct 16:08
@jamietanna jamietanna
v1.16.0
d663b6c
Compare
Choose a tag to compare
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

Full Changelog: v1.15.0...v1.16.0

Contributors

jamietanna
Assets 2

v1.15.0: Remove issues with Go 1.21

11 Sep 08:16
@jamietanna jamietanna
v1.15.0
af55078
Compare
Choose a tag to compare
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

New Contributors

Full Changelog: v1.14.0...v1.15.0

Contributors

jamietanna and namco1992
Assets 2

v1.14.0: Iris Support, Go 1.20 requirement, reduction of runtime dependencies, and various other features and fixes

30 Aug 20:07
@jamietanna jamietanna
v1.14.0
beb29bb
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v1.14.0: Iris Support, Go 1.20 requirement, reduction of runtime dependencies, and various other features and fixes

Key callouts

What's Changed

New Contributors

Full Changelog: v1.13.4...v1.14.0

Contributors

alexandear, jamietanna, and 6 other contributors
Assets 2

v1.13.4

07 Aug 15:04
@jamietanna jamietanna
v1.13.4
e90f06d
Compare
Choose a tag to compare
v1.13.4

What's Changed

Full Changelog: v1.13.3...v1.13.4

Contributors

jamietanna
Assets 2