From 3fad72f1152a82f975daf122b6c5ea41fe117969 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 11 Nov 2025 12:30:37 -0500 Subject: [PATCH 01/23] docs: updates readme announcement for 3.2 support Signed-off-by: Vincent Biret --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 99d0a1aee..6a7f787f8 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ Project Objectives: - Install core Nuget package [**Microsoft.OpenApi**](https://www.nuget.org/packages/Microsoft.OpenApi) - Install Yaml Reader Nuget package [**Microsoft.OpenApi.YamlReader**](https://www.nuget.org/packages/Microsoft.OpenApi.YamlReader) -> Note: we just released a new major version of the library, which brings support for OpenAPI 3.1! -> You can read more about the changes of this upcoming version [in the upgrade guide](./docs/upgrade-guide-2.md). +> Note: we just released a new major version of the library, which brings support for OpenAPI 3.2! +> You can read more about the changes of this upcoming version [in the upgrade guide](./docs/upgrade-guide-3.md). # Processors The OpenAPI.NET project holds the base object model for representing OpenAPI documents as .NET objects. Some developers have found the need to write processors that convert other data formats into this OpenAPI.NET object model. We'd like to curate that list of processors in this section of the readme. From 0b379b874c309d5396566877c39ad35c774a6116 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 11 Nov 2025 14:36:06 -0500 Subject: [PATCH 02/23] docs: fixes project names in contributing (wasn't updated when releasing v2) Signed-off-by: Vincent Biret --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2907d3e9..83f12f5f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ OpenAPI.net is a mono-repo containing source code for the following packages: | Library | NuGet Release | |----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Microsoft.OpenAPI](./src/Microsoft.OpenAPI/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI/) | -| [Microsoft.OpenAPI.Readers](./src/Microsoft.OpenAPI.Readers/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI.Readers?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI.Readers/) | +| [Microsoft.OpenAPI.YamlReader](./src/Microsoft.OpenApi.YamlReader/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI.YamlReader?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI.YamlReader/) | | [Microsoft.OpenAPI.Hidi](./src/Microsoft.OpenAPI.Hidi/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI.Hidi?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI.Hidi/) | OpenAPI.net is open to contributions. There are a couple of different recommended paths to get contributions into the released version of this library. From deb0c8805dcf9f5e7ffa2f1e4b17370edcc55040 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 11 Nov 2025 21:05:10 +0000 Subject: [PATCH 03/23] Bump Microsoft.Extensions.Logging.Abstractions from 9.0.10 to 10.0.0 --- updated-dependencies: - dependency-name: Microsoft.Extensions.Logging.Abstractions dependency-version: 10.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj index 465e23082..c7456e9f1 100644 --- a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj +++ b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj @@ -30,7 +30,7 @@ - + From 2e2651b5c815ace3c2e6e7f2752e3b67b049798c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 11 Nov 2025 21:06:02 +0000 Subject: [PATCH 04/23] Bump Microsoft.Extensions.DependencyInjection and 2 others Bumps Microsoft.Extensions.DependencyInjection from 9.0.10 to 10.0.0 Bumps Microsoft.Extensions.Logging from 9.0.10 to 10.0.0 Bumps Microsoft.Extensions.Logging.Debug from 9.0.10 to 10.0.0 --- updated-dependencies: - dependency-name: Microsoft.Extensions.DependencyInjection dependency-version: 10.0.0 dependency-type: direct:production update-type: version-update:semver-major - dependency-name: Microsoft.Extensions.Logging dependency-version: 10.0.0 dependency-type: direct:production update-type: version-update:semver-major - dependency-name: Microsoft.Extensions.Logging.Debug dependency-version: 10.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- performance/resultsComparer/resultsComparer.csproj | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/performance/resultsComparer/resultsComparer.csproj b/performance/resultsComparer/resultsComparer.csproj index c409872f6..6a85023cc 100644 --- a/performance/resultsComparer/resultsComparer.csproj +++ b/performance/resultsComparer/resultsComparer.csproj @@ -8,10 +8,10 @@ - - + + - + From 0844498da7ef3c321078171b57fc3e723a7159ba Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 11 Nov 2025 21:09:08 +0000 Subject: [PATCH 05/23] Bump Microsoft.NET.Test.Sdk from 18.0.0 to 18.0.1 --- updated-dependencies: - dependency-name: Microsoft.NET.Test.Sdk dependency-version: 18.0.1 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: Microsoft.NET.Test.Sdk dependency-version: 18.0.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- .../Microsoft.OpenApi.Hidi.Tests.csproj | 2 +- .../Microsoft.OpenApi.Readers.Tests.csproj | 2 +- test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/test/Microsoft.OpenApi.Hidi.Tests/Microsoft.OpenApi.Hidi.Tests.csproj b/test/Microsoft.OpenApi.Hidi.Tests/Microsoft.OpenApi.Hidi.Tests.csproj index 5b5b5fedf..b7153019d 100644 --- a/test/Microsoft.OpenApi.Hidi.Tests/Microsoft.OpenApi.Hidi.Tests.csproj +++ b/test/Microsoft.OpenApi.Hidi.Tests/Microsoft.OpenApi.Hidi.Tests.csproj @@ -14,7 +14,7 @@ - + diff --git a/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj b/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj index 39befa33f..2cad1eba3 100644 --- a/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj +++ b/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj @@ -17,7 +17,7 @@ - + diff --git a/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj b/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj index 98b459aa6..4e18c7dab 100644 --- a/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj +++ b/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj @@ -11,7 +11,7 @@ - + From d4958a803ced013260be89ba6b19ef3641a75082 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 12 Nov 2025 08:25:09 -0500 Subject: [PATCH 06/23] ci: adds a microsoft extensions group --- .github/dependabot.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index d82ae27c9..95fa5a2dc 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,21 +5,22 @@ updates: directory: "/" open-pull-requests-limit: 10 schedule: - interval: "weekly" + interval: "daily" - package-ecosystem: "nuget" # location of package manifests directory: "/" open-pull-requests-limit: 10 schedule: interval: "daily" + groups: + MicrosoftExtensions: + - "Microsoft.Extensions.*" - package-ecosystem: dotnet-sdk directory: / schedule: - interval: weekly - day: wednesday + interval: "daily" ignore: - dependency-name: '*' update-types: - version-update:semver-major - version-update:semver-minor -# Built with ❤ by [Pipeline Foundation](https://pipeline.foundation) From 9a3bf1b10fa292a79bb8cec86e9641b912010744 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 21:04:11 +0000 Subject: [PATCH 07/23] chore(deps): bump dotnet-sdk from 8.0.415 to 8.0.416 Bumps [dotnet-sdk](https://github.com/dotnet/sdk) from 8.0.415 to 8.0.416. - [Release notes](https://github.com/dotnet/sdk/releases) - [Commits](https://github.com/dotnet/sdk/compare/v8.0.415...v8.0.416) --- updated-dependencies: - dependency-name: dotnet-sdk dependency-version: 8.0.416 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- global.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/global.json b/global.json index 4c2f00caf..3d946171e 100644 --- a/global.json +++ b/global.json @@ -1,5 +1,5 @@ { "sdk": { - "version": "8.0.415" + "version": "8.0.416" } } \ No newline at end of file From ef7dc35b5e4407fcae44a11ef44feaae2614dc8a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 21:06:31 +0000 Subject: [PATCH 08/23] Bump Microsoft.Extensions.Logging and Microsoft.Extensions.Logging.Debug Bumps Microsoft.Extensions.Logging from 9.0.10 to 10.0.0 Bumps Microsoft.Extensions.Logging.Debug from 9.0.10 to 10.0.0 --- updated-dependencies: - dependency-name: Microsoft.Extensions.Logging dependency-version: 10.0.0 dependency-type: direct:production update-type: version-update:semver-major - dependency-name: Microsoft.Extensions.Logging.Debug dependency-version: 10.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj index c7456e9f1..73b681f2b 100644 --- a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj +++ b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj @@ -29,10 +29,10 @@ - + - + runtime; build; native; contentfiles; analyzers; buildtransitive all From bc0ffc908aca73ed6a9afa00e9ef82b7733984cd Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 12 Nov 2025 16:11:39 -0500 Subject: [PATCH 09/23] chore: upgrades system.text.json for performance and test projects only --- performance/resultsComparer/resultsComparer.csproj | 2 +- .../Microsoft.OpenApi.Readers.Tests.csproj | 2 +- test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/performance/resultsComparer/resultsComparer.csproj b/performance/resultsComparer/resultsComparer.csproj index 6a85023cc..aee9607c9 100644 --- a/performance/resultsComparer/resultsComparer.csproj +++ b/performance/resultsComparer/resultsComparer.csproj @@ -13,7 +13,7 @@ - + diff --git a/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj b/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj index 2cad1eba3..d1d237681 100644 --- a/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj +++ b/test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj @@ -19,7 +19,7 @@ - + diff --git a/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj b/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj index 4e18c7dab..aac7c907f 100644 --- a/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj +++ b/test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj @@ -13,7 +13,7 @@ - + From 2c0a32003e69f5308f29669e7a036f55286e93ad Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 10:31:51 -0500 Subject: [PATCH 10/23] chore: upgrades microsoft extensions deps --- performance/resultsComparer/resultsComparer.csproj | 2 +- src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/performance/resultsComparer/resultsComparer.csproj b/performance/resultsComparer/resultsComparer.csproj index aee9607c9..24b7a3a41 100644 --- a/performance/resultsComparer/resultsComparer.csproj +++ b/performance/resultsComparer/resultsComparer.csproj @@ -10,7 +10,7 @@ - + diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj index 73b681f2b..a069c77b2 100644 --- a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj +++ b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj @@ -31,7 +31,7 @@ - + runtime; build; native; contentfiles; analyzers; buildtransitive From 6a91750fc46924b0d6fcaffab7e7e353f6a01361 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 10:35:55 -0500 Subject: [PATCH 11/23] chore: upgrades openapi deps for alignment --- src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj index 73b681f2b..81d0f03af 100644 --- a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj +++ b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj @@ -39,8 +39,8 @@ - - + + From 439994d7137969617e1772e1f9a2a0c490c1c232 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 10:39:17 -0500 Subject: [PATCH 12/23] chore: upgrades commandline deps to stable version --- performance/resultsComparer/resultsComparer.csproj | 2 +- src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/performance/resultsComparer/resultsComparer.csproj b/performance/resultsComparer/resultsComparer.csproj index aee9607c9..888baa404 100644 --- a/performance/resultsComparer/resultsComparer.csproj +++ b/performance/resultsComparer/resultsComparer.csproj @@ -12,7 +12,7 @@ - + diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj index 73b681f2b..fe7e6b8f0 100644 --- a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj +++ b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj @@ -37,7 +37,7 @@ runtime; build; native; contentfiles; analyzers; buildtransitive all - + From 945f37bbe7a55601ff67ed29c756d3b92d314866 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 11:06:09 -0500 Subject: [PATCH 13/23] docs: clarifies versions mapping between integrations --- CONTRIBUTING.md | 15 ++++++++------- docs/upgrade-guide-2.md | 10 +++++++++- docs/upgrade-guide-3.md | 12 ++++++++++++ 3 files changed, 29 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83f12f5f1..f51a0ee15 100644 --- a/CONTRIBUTING.md +++ b/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 version 11 and above will adopt version 3 or above of this library. ### Multi-versions requirement for contributions diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index 5546e4896..b3c13b344 100644 --- a/docs/upgrade-guide-2.md +++ b/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 + +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. + +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. + +The latest support policy information for this library, and integration with ASP.NET 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 diff --git a/docs/upgrade-guide-3.md b/docs/upgrade-guide-3.md index 15c7e7748..dc7eb5f5b 100644 --- a/docs/upgrade-guide-3.md +++ b/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 + +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. + +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. + +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. + +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. + +The latest support policy information for this library, and integration with ASP.NET 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. From 3274dec8a44c61ce11a475f198cfb240347f1cba Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 11:42:24 -0500 Subject: [PATCH 14/23] Apply suggestions from code review Co-authored-by: Martin Costello --- CONTRIBUTING.md | 8 ++++---- docs/upgrade-guide-2.md | 2 +- docs/upgrade-guide-3.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f51a0ee15..195723567 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,15 +30,15 @@ The following table outlines the mapping between package major versions, dotnet | 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) ¹ | +| 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: > > 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 version 11 and above will adopt version 3 or above 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 diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index b3c13b344..60cca29ee 100644 --- a/docs/upgrade-guide-2.md +++ b/docs/upgrade-guide-2.md @@ -20,7 +20,7 @@ If you are using this library with [AspNetCore OpenAPI versions](https://www.nug 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. -The latest support policy information for this library, and integration with ASP.NET can be found on [the contributing documentation](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy). +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 diff --git a/docs/upgrade-guide-3.md b/docs/upgrade-guide-3.md index dc7eb5f5b..e4640d07e 100644 --- a/docs/upgrade-guide-3.md +++ b/docs/upgrade-guide-3.md @@ -7,7 +7,7 @@ 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 +## 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. @@ -15,9 +15,9 @@ If you are using this library with [AspNetCore OpenAPI versions](https://www.nug 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. -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. +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. -The latest support policy information for this library, and integration with ASP.NET can be found on [the contributing documentation](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy). +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 From 0ff4587f17b7d089bf8c5ae33591f3417199d0e0 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 11:42:40 -0500 Subject: [PATCH 15/23] Update docs/upgrade-guide-2.md --- docs/upgrade-guide-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index 60cca29ee..876dbe2e0 100644 --- a/docs/upgrade-guide-2.md +++ b/docs/upgrade-guide-2.md @@ -14,7 +14,7 @@ OpenAPI.NET v2 is a major update to the OpenAPI.NET library. This release includ > [!WARNING] > This is a major version update that includes breaking changes. Please review this guide carefully before upgrading. -## Integrations with ASP.NET +## 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. From 96e3d0f165ff5a2a98aa5bcde8cf2b4a3e14527d Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 11:44:05 -0500 Subject: [PATCH 16/23] docs: clarifies the compatibility statement Signed-off-by: Vincent Biret --- docs/upgrade-guide-2.md | 4 ++-- docs/upgrade-guide-3.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index 876dbe2e0..14eaacdf0 100644 --- a/docs/upgrade-guide-2.md +++ b/docs/upgrade-guide-2.md @@ -16,9 +16,9 @@ OpenAPI.NET v2 is a major update to the OpenAPI.NET library. This release includ ## 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. +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. +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). diff --git a/docs/upgrade-guide-3.md b/docs/upgrade-guide-3.md index e4640d07e..e874a8998 100644 --- a/docs/upgrade-guide-3.md +++ b/docs/upgrade-guide-3.md @@ -9,13 +9,13 @@ We are excited to announce OpenAPI.NET v3.0! This major update introduces suppor ## 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. +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. +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. +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. +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). From e312af9fd98d75d8ea6f914f58955804305010de Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 13 Nov 2025 21:04:25 +0000 Subject: [PATCH 17/23] Bump BenchmarkDotNet and BenchmarkDotNet.Diagnostics.Windows Bumps BenchmarkDotNet from 0.15.6 to 0.15.7 Bumps BenchmarkDotNet.Diagnostics.Windows from 0.15.6 to 0.15.7 --- updated-dependencies: - dependency-name: BenchmarkDotNet dependency-version: 0.15.7 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: BenchmarkDotNet.Diagnostics.Windows dependency-version: 0.15.7 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- performance/benchmark/PerformanceTests.csproj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/performance/benchmark/PerformanceTests.csproj b/performance/benchmark/PerformanceTests.csproj index b3c779c35..7e4937daf 100644 --- a/performance/benchmark/PerformanceTests.csproj +++ b/performance/benchmark/PerformanceTests.csproj @@ -14,8 +14,8 @@ CA1822 - - + + From 3fa8ca215c8c9884aa88a786f83119e733d1a18e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 13 Nov 2025 21:05:24 +0000 Subject: [PATCH 18/23] Bump Microsoft.OData.Edm from 8.4.2 to 8.4.3 --- updated-dependencies: - dependency-name: Microsoft.OData.Edm dependency-version: 8.4.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj index a7cb5111f..b6afc5950 100644 --- a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj +++ b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj @@ -38,7 +38,7 @@ all - + From d86f230343fa55dd4ae55f18ca914e527f4a2637 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 14 Nov 2025 10:12:49 -0500 Subject: [PATCH 19/23] ci: updates build scripts reader path Signed-off-by: Vincent Biret --- build.cmd | 4 ++-- build.sh | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/build.cmd b/build.cmd index 43cc95956..07daf7b6c 100644 --- a/build.cmd +++ b/build.cmd @@ -6,9 +6,9 @@ dotnet msbuild %PROJ% /t:restore /p:Configuration=Release dotnet msbuild %PROJ% /t:build /p:Configuration=Release dotnet msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts -Echo Building Microsoft.OpenApi.Readers +Echo Building Microsoft.OpenApi.YamlReader -SET PROJ=%~dp0src\Microsoft.OpenApi.Readers\Microsoft.OpenApi.Readers.csproj +SET PROJ=%~dp0src\Microsoft.OpenApi.YamlReader\Microsoft.OpenApi.YamlReader.csproj dotnet msbuild %PROJ% /t:restore /p:Configuration=Release dotnet msbuild %PROJ% /t:build /p:Configuration=Release dotnet msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts diff --git a/build.sh b/build.sh index e716aa272..0de30b6df 100755 --- a/build.sh +++ b/build.sh @@ -7,9 +7,9 @@ dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release dotnet msbuild "$PROJ" /t:build /p:Configuration=Release dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts" -echo "Building Microsoft.OpenApi.Readers" +echo "Building Microsoft.OpenApi.YamlReader" -PROJ="$(dirname "$0")/src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj" +PROJ="$(dirname "$0")/src/Microsoft.OpenApi.YamlReader/Microsoft.OpenApi.YamlReader.csproj" dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release dotnet msbuild "$PROJ" /t:build /p:Configuration=Release dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts" From 1e75f9a5d7021a8505eeeab730339b3b7e619baa Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 14 Nov 2025 10:13:50 -0500 Subject: [PATCH 20/23] ci: suppresses error about compiler mismatch for performance test project --- performance/benchmark/PerformanceTests.csproj | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/performance/benchmark/PerformanceTests.csproj b/performance/benchmark/PerformanceTests.csproj index 7e4937daf..53c0784d7 100644 --- a/performance/benchmark/PerformanceTests.csproj +++ b/performance/benchmark/PerformanceTests.csproj @@ -11,7 +11,8 @@ true Release false - CA1822 + + CA1822;CS9057; From 2c4d5176718d0cd2d8275a6b37c130a557538ba5 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 14 Nov 2025 10:35:54 -0500 Subject: [PATCH 21/23] ci: fixes dependabot configuration --- .github/dependabot.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 95fa5a2dc..87b987112 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -14,6 +14,7 @@ updates: interval: "daily" groups: MicrosoftExtensions: + patterns: - "Microsoft.Extensions.*" - package-ecosystem: dotnet-sdk directory: / From 0ca10db3bb9ffa937dd35862068926f3586d6991 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 17 Nov 2025 09:48:00 -0500 Subject: [PATCH 22/23] fix: empty strings should be quoted in yaml --- .../YamlConverter.cs | 5 +++-- .../YamlConverterTests.cs | 17 +++++++++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/src/Microsoft.OpenApi.YamlReader/YamlConverter.cs b/src/Microsoft.OpenApi.YamlReader/YamlConverter.cs index 710f20c6b..1cafea77b 100644 --- a/src/Microsoft.OpenApi.YamlReader/YamlConverter.cs +++ b/src/Microsoft.OpenApi.YamlReader/YamlConverter.cs @@ -140,9 +140,10 @@ ScalarStyle.Plain when YamlNullRepresentations.Contains(yaml.Value) => (JsonValu } private static bool NeedsQuoting(string value) => + string.IsNullOrEmpty(value) || decimal.TryParse(value, NumberStyles.Float, CultureInfo.InvariantCulture, out _) || - bool.TryParse(value, out _) || - YamlNullRepresentations.Contains(value); + bool.TryParse(value, out _) || + YamlNullRepresentations.Contains(value); private static YamlScalarNode ToYamlScalar(this JsonValue val) { diff --git a/test/Microsoft.OpenApi.Readers.Tests/YamlConverterTests.cs b/test/Microsoft.OpenApi.Readers.Tests/YamlConverterTests.cs index b2f0e0f5d..c246e0898 100644 --- a/test/Microsoft.OpenApi.Readers.Tests/YamlConverterTests.cs +++ b/test/Microsoft.OpenApi.Readers.Tests/YamlConverterTests.cs @@ -315,6 +315,23 @@ public void ItDoesNotSerializeTheSentinelValue() var scalarNode = Assert.IsType(yamlValue); Assert.Equal("null", scalarNode.Value, StringComparer.OrdinalIgnoreCase); } + [Fact] + public void RoundTripEmptyStringsValues() + { + // Given + var yamlInput = + """ + emptyString: "" + """; + + // When + var jsonNode = ConvertYamlStringToJsonNode(yamlInput); + var convertedBack = jsonNode.ToYamlNode(); + var convertedBackOutput = ConvertYamlNodeToString(convertedBack); + + // Then + Assert.Equal(yamlInput.MakeLineBreaksEnvironmentNeutral(), convertedBackOutput.MakeLineBreaksEnvironmentNeutral()); + } private static JsonNode ConvertYamlStringToJsonNode(string yamlInput) { From 974a9517636bbf39991e4e788dd200539a0192d4 Mon Sep 17 00:00:00 2001 From: "release-please-token-provider[bot]" <225477224+release-please-token-provider[bot]@users.noreply.github.com> Date: Mon, 17 Nov 2025 14:58:46 +0000 Subject: [PATCH 23/23] chore(main): release 3.0.1 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ Directory.Build.props | 2 +- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4191c8899..56441f9d3 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.0.0" + ".": "3.0.1" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index f2561d642..98861fe62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [3.0.1](https://github.com/microsoft/OpenAPI.NET/compare/v3.0.0...v3.0.1) (2025-11-17) + + +### Bug Fixes + +* empty strings should be quoted in yaml ([8d215f9](https://github.com/microsoft/OpenAPI.NET/commit/8d215f9ea8a780b1e2e8dd6cefb8d470cc35682d)) +* empty strings should be quoted in yaml ([0ca10db](https://github.com/microsoft/OpenAPI.NET/commit/0ca10db3bb9ffa937dd35862068926f3586d6991)) + ## [3.0.0](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.9...v3.0.0) (2025-11-11) diff --git a/Directory.Build.props b/Directory.Build.props index fa48dd7ac..476cfb435 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -12,7 +12,7 @@ https://github.com/Microsoft/OpenAPI.NET © Microsoft Corporation. All rights reserved. OpenAPI .NET - 3.0.0 + 3.0.1