Home Original page

oapi-codegen v2 is coming · oapi-codegen/oapi-codegen · Discussion #1309

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 👏