oapi-codegen v2 is coming

[jamietanna]

Hey folks! Marcin and I would like to make y'all aware of an upcoming change to oapi-codegen that we've been discussing, which will bring a breaking change to the module.

---

Important

TL;DR: We will be releasing oapi-codegen v2 on November 1st. This will have some breaking changes.
A full list of proposed changes can be found below, but the key changes are to remove any deprecated packages from deepmap/oapi-codegen.

---

Although this is planned to be a breaking change, hence the move to v2, we are planning on this being as minimally breaking as possible. We want to remove a couple of now deprecated pieces of the library as quickly as possible, without making this a painful migration for you all.

As you may have noticed, we've recently split out a few modules from the core project into their own separate Go modules, which now sit under the oapi-codegen organisation.

We will no longer be supporting v1 after the release of v2, but as mentioned, this release is not meant to introduce any breaking changes. If you're already running v1.14.0 or v1.15.0, you'll be unaffected by these changes.

Changes planned for this release (milestone link):

Move pkg/testutil to its own package + remove it

Similar to the below changes, we'll also be moving pkg/testutil to its own package, and then removing it as part of this release.

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.

Other notes

We have plans for a much more considerable overhaul of the package + generated code, but would prefer to release v2 with the small set of changes and impact mentioned above, while we prepare the v3 release that will require a full migration, and will require us to provide support for both v2 and v3 for a to-be-determined lifetime.

Props

A big thank you to @pgier in #1142 for initially flagging this 👏

[jamietanna]

If you would like to confirm if you're affected by the upcoming removal of these packages you can see the changes here and apply the changes by running:

go get github.com/deepmap/oapi-codegen@725742edf004d2aea927a23e0fad85a495457ec4
# depending on how your project works, you may need to update references for the `/cmd/` package too
go mod tidy
go generate ./...

This should show no compilation issues.

[jamietanna]

Updated to be the "final" version of the branch, now 👍

[jamietanna]

Also of note - I'll make sure to triage PRs and issues that now need to be moved out of this repo into the specific repos they should fit under

[jamietanna]

Discussion in #1310 (comment) would remove pkg/testutil, which would be a slightly bigger breaking change - will update announcement above if we decide to do this

Done

[pcriv]

Is the chi-middleware staying around as its own module? I don't see it here yet

[jamietanna]

Good question! No, the chi-middleware never was specific to chi and was something we took the opportunity to correct it to just be nethttp-middleware

[jamietanna]

#1334 will be released in the next couple of days to give folks time to take advantage of the new repos for middlewares ahead of v2.

[jamietanna]

And it's live 🚀 https://github.com/deepmap/oapi-codegen/releases/tag/v2.0.0

[lzap]

Just finished upgrade, I was so worried and I am here to report it was super smooth. Stunning work with documenting this and well handled. Thanks a bunch! 👍🏻