Merge pull request #2602 from microsoft/docs/swashbuckle-versions

docs: clarifies versions mapping between integrations

Author: baywet

CONTRIBUTING.md

@@ -28,16 +28,17 @@ Because one major consumer of these libraries is ASP.net, the support policy of
 
 The following table outlines the mapping between package major versions, dotnet versions, and which contributions are accepted. As a consumer, make sure the version of this library your application is using is aligned with the version of ASP.net described in the table below.
 
-| Major version | Branch     | Supported ASP.NET versions | Supported OpenAPI versions | Changes provided by Microsoft               | Accepted contributions                      | End of support date |
-| ------------- | ---------- | -------------------------- | -------------------------- | ------------------------------------------- | ------------------------------------------- | --------------- |
-| 1.X           | support/v1 | < 10                       | 2.0, 3.0                   | security fixes                              | security and bugfixes                       | net 9 (Nov 2026)           |
-| 2.X           | support/v2 | = 10 *                     | 2.0, 3.0, 3.1              | security and bugfixes                       | security and bugfixes                       | net 10 (Nov 2028) * |
-| 3.X           | main       | not available              | 2.0, 3.0, 3.1, 3.2         | security, bugfixes and feature improvements | security, bugfixes and feature improvements | TBD ** |
+| Major version | Branch     | Supported [AspNetCore OpenAPI versions](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi)  | Supported [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) | Supported OpenAPI versions | Changes provided by Microsoft               | Accepted contributions                      | End of support date |
+| ------------- | ---------- | -------------------------- | ---------- | -------------------------- | ------------------------------------------- | ------------------------------------------- | --------------- |
+| 1.X           | support/v1 | < 10                       | < 10          | 2.0, 3.0                   | security fixes                              | security and bugfixes                       | .NET 9 (Nov 2026)           |
+| 2.X           | support/v2 | = 10 ¹                     | = 10 ³        | 2.0, 3.0, 3.1              | security and bugfixes                       | security and bugfixes                       | .NET 10 (Nov 2028) ¹ |
+| 3.X  ²        | main       | not available              | not available | 2.0, 3.0, 3.1, 3.2         | security, bugfixes and feature improvements | security, bugfixes and feature improvements | TBD  |
 
 > Notes:
 >
-> * This assumes that NET 11 and above will adopt version 3 or above of this library, otherwise, it'd expand the support date for version 2 of this library.
-> ** This will be conditioned by new releases of OpenAPI, this library, asp.net and asp.net's adoptions of new versions of this library.
+> 1. This assumes that AspNetCore OpenAPI version 11 and above will adopt version 3 or above of this library, otherwise, it'd expand the support date for version 2 of this library.
+> 2. This will be conditioned by new releases of OpenAPI, this library, ASP.NET and AspNetCore OpenAPI's adoption of new versions of this library.
+> 3. This assumes that Swashbuckle.AspNetCore version 11 and above will adopt version 3 or above of this library.
 
 ### Multi-versions requirement for contributions
 

docs/upgrade-guide-2.md

@@ -12,7 +12,15 @@ We are excited to announce the new version of the OpenAPI.NET library!
 OpenAPI.NET v2 is a major update to the OpenAPI.NET library. This release includes a number of performance improvements, API enhancements, and support for OpenAPI v3.1.
 
 > [!WARNING]
-> If you are using this library with ASP.NET Core version `< 10.0` then you must remain on version `1.x` as it's not compatible.
+> This is a major version update that includes breaking changes. Please review this guide carefully before upgrading.
+
+## Integrations with ASP.NET Core
+
+If you are using this library with [AspNetCore OpenAPI versions](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) `< 10.0` then you must remain on version `1.x` as it's not compatible with version 2 or above of this library.
+
+If you are using this library with [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) `< 10.0` then you must remain on version `1.x` as it's not compatible with version 2 or above of this library.
+
+The latest support policy information for this library, and integration with ASP.NET Core can be found on [the contributing documentation](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy).
 
 ## The biggest update ever
 

docs/upgrade-guide-3.md

@@ -7,6 +7,18 @@ We are excited to announce OpenAPI.NET v3.0! This major update introduces suppor
 > [!WARNING]
 > This is a major version update that includes breaking changes. Please review this guide carefully before upgrading.
 
+## Integrations with ASP.NET Core
+
+If you are using this library with [AspNetCore OpenAPI versions](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) `< 10.0` then you must remain on version `1.x` as it's not compatible with version 3 or above of this library.
+
+If you are using this library with [AspNetCore OpenAPI versions](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) `= 10.0` then you must remain on version `2.x` as it's not compatible with version 3 or above of this library.
+
+If you are using this library with [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) `< 10.0` then you must remain on version `1.x` as it's not compatible with version 3 or above of this library.
+
+If you are using this library with [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) `= 10.0` then you must remain on version `2.x` as it's not compatible with version 3 or above of this library.
+
+The latest support policy information for this library, and integration with ASP.NET Core can be found on [the contributing documentation](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy).
+
 ## OpenAPI v3.2 Support
 
 The primary focus of OpenAPI.NET v3.0 is adding comprehensive support for OpenAPI specification v3.2. This includes new serialization methods, enhanced model properties, and expanded functionality across the entire API surface.