The Swagger v4 effort has finally come to a fruitful conclusion. It has been an incredible journey, and we'd especially like to thank our community members who helped the v4 effort progress. Their contributions allowed us to quickly identify and resolve various bugs and anomalies throughout the release candidate process.
Both SwaggerUI and SwaggerEditor primary branches are running on the latest versions of React 17.x and Redux 4.x. Along with making these two major dependency changes, we updated and pruned many of the other dependencies. This results in a more secure, more stable, and more streamlined dependency tree.
The most significant benefit from the v4 releases is that plugins of SwaggerUI and SwaggerEditor can now use function (a.k.a. functional) components and all the latest features that React 17 brings. This includes Hooks, Context API, new lifecycle methods, new event handlers, error boundaries, and more.
What are the breaking changes?
For anyone not integrating SwaggerUI or SwaggerEditor as a React library, there are no breaking changes. The v4 releases will continue to support OpenAPI 3.0.x and Swagger 2.0 as before. For library maintainers, the only breaking change introduced is dropping support for older versions of React and Redux.
To ensure a smooth upgrade, when using v4, update all React code to support React@17. If this proves impossible, an alternative is to run two versions of React, a practice known as gradual upgrade. A guide can be found at https://github.com/reactjs/react-gradual-upgrade-demo/.
There are no other breaking changes in the SwaggerUI API, plugin system, or any other part of the codebase.
Why a new major (v4) version?
In the past, SwaggerUI and SwaggerEditor versioning have followed the OpenAPI specification versions. When OpenAPI 3.0.0 was released, SwaggerUI and SwaggerEditor followed with their respective v3 versions. This versioning structure, while initially simple to understand and easy to market, does have issues when it comes to integrating Swagger as a library, something that we as consumers of other libraries empathize with. As such, we have made the decision to break away from this approach and to adopt semantic versioning where possible. The v4 releases are the start of adding new and exciting features to the Swagger tooling, all of which begin with updating to the latest available streamlined dependency tree.
How you can explore Swagger v4 today
The v4 npm packages for SwaggerUI and SwaggerEditor are available on npmjs.com and will be the latest stable versions. You can install these packages via the command line, npm install [-D|-S] swagger-ui@4.
The lifespan of 3.x branches
We will continue to support the 3.x branches through the end of November 2021. During the 3.x maintenance period, we'll backport security and/or bug fixes to 3.x branches and issue v3 patch releases. No new features will be added to the v3 branches.