diff --git a/README.md b/README.md index f0df85fee4..159eeecbd4 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/docs/migrating-to-v10.md b/docs/migrating-to-v10.md index 354e55b2b2..c9c0b4ddf2 100644 --- a/docs/migrating-to-v10.md +++ b/docs/migrating-to-v10.md @@ -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 @@ -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]_. @@ -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"