Skip to content

Clarify compatibility #3694

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
martincostello merged 1 commit into from
Dec 2, 2025
Merged

Clarify compatibility #3694

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 6 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,12 @@ for more details.

## Compatibility

| **Swashbuckle Version** | **ASP.NET Core** | **OpenAPI/Swagger Versions** | **Microsoft.OpenApi** | **swagger-ui** | **Redoc** |
|:-----------------------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------------|:---------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------|
| [![CI Swashbuckle.AspNetCore version][swashbuckle-version-vnext-badge]][swashbuckle-version-vnext-release] | >= 8.0.0 | 3.1, **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-vnext-badge]][openapi-version-vnext-release] | [![swagger-ui version][swaggerui-version-vnext-badge]][swaggerui-version-vnext-release] | [![Redoc version][redoc-version-vnext-badge]][redoc-version-vnext-release] |
| [![Latest Swashbuckle.AspNetCore version][swashbuckle-version-latest-badge]][swashbuckle-version-latest-release] | >= 8.0.0 | 3.1, **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-latest-badge]][openapi-version-latest-release] | [![swagger-ui version][swaggerui-version-latest-badge]][swaggerui-version-latest-release] | [![Redoc version][redoc-version-latest-badge]][redoc-version-latest-release] |
| [![Last v9 Swashbuckle.AspNetCore version][swashbuckle-version-v9-badge]][swashbuckle-version-v9-release] | >= 8.0.0 | **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-v9-badge]][openapi-version-v9-release] | [![swagger-ui version][swaggerui-version-v9-badge]][swaggerui-version-v9-release] | [![Redoc version][redoc-version-v9-badge]][redoc-version-v9-release] |
| [![Last v8 Swashbuckle.AspNetCore version][swashbuckle-version-v8-badge]][swashbuckle-version-v8-release] | >= 8.0.0, 2.3.x | **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-v8-badge]][openapi-version-v8-release] | [![swagger-ui version][swaggerui-version-v8-badge]][swaggerui-version-v8-release] | [![Redoc version][redoc-version-v8-badge]][redoc-version-v8-release] |
| [![Last v7 Swashbuckle.AspNetCore version][swashbuckle-version-v7-badge]][swashbuckle-version-v7-release] | >= 8.0.0, 6.0.x, 2.1.x | **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-v7-badge]][openapi-version-v7-release] | [![swagger-ui version][swaggerui-version-v7-badge]][swaggerui-version-v7-release] | [![Redoc version][redoc-version-v7-badge]][redoc-version-v7-release] |
| **Swashbuckle Version** | **ASP.NET Core** | **OpenAPI/Swagger Versions** | **Microsoft.OpenApi** | **swagger-ui** | **Redoc** |
|:-----------------------------------------------------------------------------------------------------------------|:---------------------------|:-----------------------------|:---------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------|
| [![CI Swashbuckle.AspNetCore version][swashbuckle-version-vnext-badge]][swashbuckle-version-vnext-release] | >= 8.0.0 | 3.1, **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-vnext-badge]][openapi-version-vnext-release] | [![swagger-ui version][swaggerui-version-vnext-badge]][swaggerui-version-vnext-release] | [![Redoc version][redoc-version-vnext-badge]][redoc-version-vnext-release] |
| [![Latest Swashbuckle.AspNetCore version][swashbuckle-version-latest-badge]][swashbuckle-version-latest-release] | >= 8.0.0 | 3.1, **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-latest-badge]][openapi-version-latest-release] | [![swagger-ui version][swaggerui-version-latest-badge]][swaggerui-version-latest-release] | [![Redoc version][redoc-version-latest-badge]][redoc-version-latest-release] |
| [![Last v9 Swashbuckle.AspNetCore version][swashbuckle-version-v9-badge]][swashbuckle-version-v9-release] | 9.0.x, 8.0.x | **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-v9-badge]][openapi-version-v9-release] | [![swagger-ui version][swaggerui-version-v9-badge]][swaggerui-version-v9-release] | [![Redoc version][redoc-version-v9-badge]][redoc-version-v9-release] |
| [![Last v8 Swashbuckle.AspNetCore version][swashbuckle-version-v8-badge]][swashbuckle-version-v8-release] | 9.0.x, 8.0.x, 2.3.x | **3.0**, 2.0 | [![Microsoft.OpenApi version][openapi-version-v8-badge]][openapi-version-v8-release] | [![swagger-ui version][swaggerui-version-v8-badge]][swaggerui-version-v8-release] | [![Redoc version][redoc-version-v8-badge]][redoc-version-v8-release] |

[swashbuckle-version-vnext-badge]: https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2FHEAD%2FDirectory.Build.props&query=(%2F%2FProject%2FPropertyGroup%2FVersionPrefix)%5B1%5D&prefix=v&suffix=-*&logo=github&label=CI
[swashbuckle-version-vnext-release]: https://www.myget.org/gallery/domaindrivendev
Expand All @@ -46,8 +45,6 @@ for more details.
[swashbuckle-version-v9-release]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases/tag/v9.0.6
[swashbuckle-version-v8-badge]: https://img.shields.io/badge/v8-v8.1.4-blue?logo=github
[swashbuckle-version-v8-release]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases/tag/v8.1.4
[swashbuckle-version-v7-badge]: https://img.shields.io/badge/v7-v7.3.2-blue?logo=github
[swashbuckle-version-v7-release]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases/tag/v7.3.2

[openapi-version-vnext-badge]: https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2FHEAD%2Fsrc%2FSwashbuckle.AspNetCore.Swagger%2FSwashbuckle.AspNetCore.Swagger.csproj&query=%2F%2FPackageReference%5B%40Include%3D'Microsoft.OpenApi'%5D%2F%40VersionOverride&logo=openapiinitiative&label=Microsoft.OpenApi
[openapi-version-vnext-release]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/HEAD/src/Swashbuckle.AspNetCore.Swagger/Swashbuckle.AspNetCore.Swagger.csproj#L20
Expand All @@ -57,8 +54,6 @@ for more details.
[openapi-version-v9-release]: https://github.com/microsoft/OpenAPI.NET/releases/tag/v1.6.25
[openapi-version-v8-badge]: https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv8.1.4%2FDirectory.Packages.props&query=%2F%2FPackageVersion%5B%40Include%3D'Microsoft.OpenApi'%5D%2F%40Version&logo=openapiinitiative&label=Microsoft.OpenApi
[openapi-version-v8-release]: https://github.com/microsoft/OpenAPI.NET/releases/tag/1.6.23
[openapi-version-v7-badge]: https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv7.3.2%2FDirectory.Packages.props&query=%2F%2FPackageVersion%5B%40Include%3D'Microsoft.OpenApi'%5D%2F%40Version&logo=openapiinitiative&label=Microsoft.OpenApi
[openapi-version-v7-release]: https://github.com/microsoft/OpenAPI.NET/releases/tag/1.6.22

[swaggerui-version-vnext-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2FHEAD%2Fsrc%2FSwashbuckle.AspNetCore.SwaggerUI%2Fpackage.json&query=%24.dependencies.swagger-ui-dist&style=flat&label=swagger-ui
[swaggerui-version-vnext-release]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/HEAD/src/Swashbuckle.AspNetCore.SwaggerUI/package.json#L6
Expand All @@ -68,8 +63,6 @@ for more details.
[swaggerui-version-v9-release]: https://github.com/swagger-api/swagger-ui/releases/tag/v5.29.2
[swaggerui-version-v8-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv8.1.4%2Fsrc%2FSwashbuckle.AspNetCore.SwaggerUI%2Fpackage.json&query=%24.dependencies.swagger-ui-dist&style=flat&label=swagger-ui
[swaggerui-version-v8-release]: https://github.com/swagger-api/swagger-ui/releases/tag/v5.22.0
[swaggerui-version-v7-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv7.3.2%2Fsrc%2FSwashbuckle.AspNetCore.SwaggerUI%2Fpackage.json&query=%24.dependencies.swagger-ui-dist&style=flat&label=swagger-ui
[swaggerui-version-v7-release]: https://github.com/swagger-api/swagger-ui/releases/tag/v5.20.1

[redoc-version-vnext-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2FHEAD%2Fsrc%2FSwashbuckle.AspNetCore.ReDoc%2Fpackage.json&query=%24.dependencies.redoc&style=flat&label=Redoc
[redoc-version-vnext-release]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/HEAD/src/Swashbuckle.AspNetCore.ReDoc/package.json#L6
Expand All @@ -79,8 +72,6 @@ for more details.
[redoc-version-v9-release]: https://github.com/Redocly/redoc/releases/tag/v2.5.1
[redoc-version-v8-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv8.1.4%2Fsrc%2FSwashbuckle.AspNetCore.ReDoc%2Fpackage.json&query=%24.dependencies.redoc&style=flat&label=Redoc
[redoc-version-v8-release]: https://github.com/Redocly/redoc/releases/tag/v2.5.0
[redoc-version-v7-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv7.3.2%2Fsrc%2FSwashbuckle.AspNetCore.ReDoc%2Fpackage.json&query=%24.dependencies.redoc&style=flat&label=Redoc
[redoc-version-v7-release]: https://github.com/Redocly/redoc/releases/tag/v2.4.0

## Getting Started

Expand Down
16 changes: 9 additions & 7 deletions docs/migrating-to-v10.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
## Why breaking changes?

While the [OpenAPI 3.1 specification][openapi-specification] is a minor release compared to OpenAPI 3.0, the OpenAPI specification does
not use Semantic Versioning (SemVer). The changes introduced between the two versions are quite breaking in a practical sense, so major
changes were required to be made to [Microsoft.OpenApi][microsoft-openapi-package], the package which Swashbuckle.AspNetCore builds upon,
in order to allow applications to produce OpenAPI 3.1 documents.
not use [Semantic Versioning (SemVer)][semver]. The changes introduced between the two versions are quite breaking in a practical sense,
so major changes were required to be made to [Microsoft.OpenApi][microsoft-openapi-package], the package which Swashbuckle.AspNetCore
builds upon, in order to allow applications to produce OpenAPI 3.1 documents.

These changes were introduced in [Microsoft.OpenApi v2.0.0][microsoft-openapi-v2-migration-guide], which _does_ follow SemVer. As a result,
Swashbuckle.AspNetCore v10+ now depends on Microsoft.OpenApi v2+ to allow users to produce OpenAPI 3.1 documents, fulfilling a
Expand All @@ -17,10 +17,11 @@ long-standing feature request: [Plans on official support for OpenApi 3.1.0 #234
These changes are unfortunately required, even if you still wish to target Swagger 2.0 or OpenAPI 3.0 documents, as the same library is used
to produce all three document format versions.

For the same breaking changes, ASP.NET Core v10+ also depends on Microsoft.OpenApi v2+, so these changes were also required to allow applications
using ASP.NET Core 10 to use Swashbuckle.AspNetCore effectively with minimal friction. This also helps support users who may wish to migrate an
application from Swashbuckle.AspNetCore to Microsoft.AspNetCore.OpenApi (for example if they need native AoT support). More information about the
breaking changes in ASP.NET Core 10 can be found in this document: _[What's new in ASP.NET Core in .NET 10][breaking-changes-aspnetcore]_.
For the same reason, ASP.NET Core v10+ also depends on Microsoft.OpenApi v2+ if you use the [Microsoft.AspNetCore.OpenApi][microsoft-aspnetcore-openapi-package]
NuGet package, so these changes were also required to allow applications using ASP.NET Core 10 to use Swashbuckle.AspNetCore effectively with
minimal friction. This also helps support users who may wish to migrate an application from Swashbuckle.AspNetCore to Microsoft.AspNetCore.OpenApi
(for example if they need native AoT support). More information about the breaking changes in ASP.NET Core 10 can be found in this
document: _[What's new in ASP.NET Core in .NET 10][breaking-changes-aspnetcore]_.

The refactoring required to support OpenAPI 3.1 in Swashbuckle.AspNetCore was significant. If you're interested in what exactly what was changed,
you can check out the PR to implement it that was worked on over the course of .NET 10's development (it's quite large): _[Support .NET 10 #3283][swashbuckle-aspnetcore-10]_.
Expand Down Expand Up @@ -100,6 +101,7 @@ Migrating to Swashbuckle.AspNetCore v10+ will likely involve changes in the foll
[microsoft-openapi-v2-migration-guide]: https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md "Microsoft OpenAPI.NET v2 migration guide"
[openapi-specification]: https://swagger.io/specification/ "OpenAPI Specification"
[security]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v10.0.0/docs/configure-and-customize-swaggergen.md#add-security-definitions-and-requirements "Add Security Definitions and Requirements"
[semver]: https://semver.org/ "Semantic Versioning 2.0.0"
[swashbuckle-aspnetcore-906]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases/tag/v9.0.6 "Swashbuckle.AspNetCore v9.0.6"
[swashbuckle-aspnetcore-10]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/3283 "Support .NET 10"
[withopenapi-deprecation]: https://github.com/aspnet/Announcements/issues/519 "[Breaking change]: Deprecation of WithOpenApi extension method"
Loading