From b2aec1347cc5383930d6585f9979eec23b020976 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 5 Jun 2025 19:54:16 -0700 Subject: [PATCH 1/5] WN update prev 5: Validaton Min API and OpenAPI --- aspnetcore/release-notes/aspnetcore-10.0.md | 2 +- .../aspnetcore-10/includes/OpenApiNetUpdatePrev.md | 8 ++++++++ .../aspnetcore-10/includes/OpenApiNetUpdatePrev17.md | 6 ------ .../includes/OpenApiPopulateXMLDocComments.md | 2 ++ .../aspnetcore-10/includes/ValidationSupportMinAPI.md | 3 +++ .../includes/ValidatonSupportMinApiExperimental.md | 0 6 files changed, 14 insertions(+), 7 deletions(-) create mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md delete mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev17.md create mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index b18926db30ad..b73a7fa8825e 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/aspnetcore/release-notes/aspnetcore-10.0.md @@ -61,7 +61,7 @@ This section describes new features for OpenAPI. [!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md)] -[!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev17.md)] +[!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md)] ### Authentication and authorization diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md new file mode 100644 index 000000000000..0f2ab9cfff70 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md @@ -0,0 +1,8 @@ +### OpenAPI.NET updated to Preview.18 + +The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation was upgraded to [v2.0.0-preview18](https://www.nuget.org/packages/Microsoft.OpenApi/2.0.0-preview.18). The v2.0.0-preview18 version improves compatibility with the updated library version. + +The previous v2.0.0-preview17 version included a number of bug fixes and improvements and also introduced some breaking changes. The breaking changes should only affect users that use document, operation, or schema transformers. Breaking changes in this iteration that may affect developers include the following: + +* [Ephemeral object properties are now in Metadata](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md#ephemeral-object-properties-are-now-in-metadata) +* [Use HTTP Method Object Instead of Enum](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md#use-http-method-object-instead-of-enum) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev17.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev17.md deleted file mode 100644 index 1da51018b6be..000000000000 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev17.md +++ /dev/null @@ -1,6 +0,0 @@ -### OpenAPI.NET updated to Preview.17 - -The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation was upgraded to [v2.0.0-preview17](https://www.nuget.org/packages/Microsoft.OpenApi/2.0.0-preview.17). This version includes a number of bug fixes and improvements and also introduces some breaking changes. The breaking changes should only affect users that use document, operation, or schema transformers. Breaking changes in this iteration that may affect developers include the following: - -* [Ephemeral object properties are now in Metadata](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md#ephemeral-object-properties-are-now-in-metadata) -* [Use HTTP Method Object Instead of Enum](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md#use-http-method-object-instead-of-enum) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md index be80ed5252ad..e8f10d236bd1 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md @@ -10,6 +10,8 @@ ASP.NET Core OpenAPI document generation will now include metadata from XML doc At build-time, the OpenAPI package will leverage a source generator to discover XML comments in the current application assembly and any project references and emit source code to insert them into the document via an OpenAPI document transformer. +Support for generating OpenAPI metadata from XML documentation comments has been extended with ASP.NET Core in .NET 10 to extract metadata for operation responses from `` and `` XML tags. + Note that the C# build process does not capture XML doc comments placed on lambda expresions, so to use XML doc comments to add metadata to a minimal API endpoint, you must define the endpoint handler as a method, put the XML doc comments on the method, and then reference that method from the `MapXXX` method. For example, to use XML doc comments to add metadata to a minimal API endpoint originally defined as a lambda expression: ```csharp diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md b/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md index 85e9628fe60b..3b15b1ac3f74 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md @@ -31,3 +31,6 @@ app.MapPost("/products", => TypedResults.Ok(productId)) .DisableValidation(); ``` + +> [!NOTE] +> Several small improvements and fixes have been made to the Minimal APIs validation generator introduced in ASP.NET Core 10. To support future enhancements, the underlying validation resolver APIs are now marked as experimental. The top-level `AddValidation` APIs and the built-in validation filter remain stable and non-experimental. diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md b/aspnetcore/release-notes/aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md new file mode 100644 index 000000000000..e69de29bb2d1 From ed3b2fc167f982de81acb601b9f4dab9228d076f Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 5 Jun 2025 21:39:43 -0700 Subject: [PATCH 2/5] Removed unused empty file --- .../aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md b/aspnetcore/release-notes/aspnetcore-10/includes/ValidatonSupportMinApiExperimental.md deleted file mode 100644 index e69de29bb2d1..000000000000 From f310c2fbdedb0acb568ac76678543835c82c95a9 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 5 Jun 2025 21:50:45 -0700 Subject: [PATCH 3/5] typo fix --- .../aspnetcore-10/includes/ValidationSupportMinAPI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md b/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md index 3b15b1ac3f74..4525d0fc7e9d 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md @@ -33,4 +33,4 @@ app.MapPost("/products", ``` > [!NOTE] -> Several small improvements and fixes have been made to the Minimal APIs validation generator introduced in ASP.NET Core 10. To support future enhancements, the underlying validation resolver APIs are now marked as experimental. The top-level `AddValidation` APIs and the built-in validation filter remain stable and non-experimental. +> Several small improvements and fixes have been made to the Minimal APIs validation generator introduced in ASP.NET Core for .NET 10. To support future enhancements, the underlying validation resolver APIs are now marked as experimental. The top-level `AddValidation` APIs and the built-in validation filter remain stable and non-experimental. From e2a03d4ea5a2503e3737ad1d335f01953e012f2f Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 6 Jun 2025 11:06:10 -0700 Subject: [PATCH 4/5] Update aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md Co-authored-by: Mike Kistler --- .../aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md index e8f10d236bd1..be80ed5252ad 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md @@ -10,8 +10,6 @@ ASP.NET Core OpenAPI document generation will now include metadata from XML doc At build-time, the OpenAPI package will leverage a source generator to discover XML comments in the current application assembly and any project references and emit source code to insert them into the document via an OpenAPI document transformer. -Support for generating OpenAPI metadata from XML documentation comments has been extended with ASP.NET Core in .NET 10 to extract metadata for operation responses from `` and `` XML tags. - Note that the C# build process does not capture XML doc comments placed on lambda expresions, so to use XML doc comments to add metadata to a minimal API endpoint, you must define the endpoint handler as a method, put the XML doc comments on the method, and then reference that method from the `MapXXX` method. For example, to use XML doc comments to add metadata to a minimal API endpoint originally defined as a lambda expression: ```csharp From 3eb47fea7c6b5102f1604c7232394acba142549f Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Mon, 9 Jun 2025 11:59:19 -0700 Subject: [PATCH 5/5] Update aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md Co-authored-by: Tom Dykstra --- .../aspnetcore-10/includes/OpenApiNetUpdatePrev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md index 0f2ab9cfff70..0b261f3e81e2 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md @@ -2,7 +2,7 @@ The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation was upgraded to [v2.0.0-preview18](https://www.nuget.org/packages/Microsoft.OpenApi/2.0.0-preview.18). The v2.0.0-preview18 version improves compatibility with the updated library version. -The previous v2.0.0-preview17 version included a number of bug fixes and improvements and also introduced some breaking changes. The breaking changes should only affect users that use document, operation, or schema transformers. Breaking changes in this iteration that may affect developers include the following: +The previous v2.0.0-preview17 version included a number of bug fixes and improvements and also introduced some breaking changes. The breaking changes should only affect users that use document, operation, or schema transformers. Breaking changes in this version that may affect developers include the following: * [Ephemeral object properties are now in Metadata](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md#ephemeral-object-properties-are-now-in-metadata) * [Use HTTP Method Object Instead of Enum](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-2.md#use-http-method-object-instead-of-enum)