From 0c85d9307b6aa0ac019e47c6cb5f892728a75e51 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 11 Aug 2025 14:26:01 -0700 Subject: [PATCH 1/8] WN: 10prev7 OpenAPI --- .../includes/formdata-enum-parameters.md | 5 +++++ .../includes/microsoft-openapi-v2upgrade.md | 4 ++++ .../includes/responseDescProducesResponseType.md | 12 ++++++------ .../includes/upgrade-microsoft-openapi-2.md | 4 ++++ .../aspnetcore-10/includes/xml-comment-generator.md | 5 +++++ 5 files changed, 24 insertions(+), 6 deletions(-) create mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/formdata-enum-parameters.md create mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md create mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/formdata-enum-parameters.md b/aspnetcore/release-notes/aspnetcore-10/includes/formdata-enum-parameters.md new file mode 100644 index 000000000000..c3f5be6a2cf6 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/includes/formdata-enum-parameters.md @@ -0,0 +1,5 @@ +### Form data enum parameters use actual enum type in OpenAPI + +Form data parameters in MVC controller actions now generate OpenAPI metadata using the actual enum type instead of defaulting to string. + +Community contribution: Thanks to [@ascott18](https://github.com/ascott18)! diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md b/aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md new file mode 100644 index 000000000000..327f34b990ce --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md @@ -0,0 +1,4 @@ +### Upgrade Microsoft.OpenApi to 2.0.0 + +The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation has been upgraded to v2.0.0 (GA). +With the update to the GA version of this package, no further breaking changes are expected in the OpenAPI document generation. diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md index 29eb865527c6..3855f82de9e2 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md @@ -1,6 +1,6 @@ -### Response description on ProducesResponseType for API controllers +### Response description on ProducesResponseType for API controllers and Minimal APIs -The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute) attributes now accept an optional string parameter, `Description`, that will set the description of the response. Here's an example: +The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute) attributes now accept an optional string parameter, `Description`, that sets the description of the response. Here's an example: ```csharp [HttpGet(Name = "GetWeatherForecast")] @@ -8,9 +8,7 @@ The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1 Description = "The weather forecast for the next 5 days.")] public IEnumerable Get() { -``` - -And the generated OpenAPI: +The following OpenAPI response and description are generated: ```json "responses": { @@ -18,6 +16,8 @@ And the generated OpenAPI: "description": "The weather forecast for the next 5 days.", "content": { ``` -[Minimal APIs](https://github.com/dotnet/aspnetcore/issues/58724) currently don't support `ProducesResponseType`. + +This functionality is supported in both [API controllers](/aspnet/core/web-api#apicontroller-attribute) and [Minimal APIs](/aspnet/core/fundamentals/minimal-apis). For Minimal APIs, the `Description` property is correctly set even when the attribute’s type and the inferred return type aren't an exact match. + [Community contribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏 diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md b/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md new file mode 100644 index 000000000000..3d495db080bd --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md @@ -0,0 +1,4 @@ +### Upgrade Microsoft.OpenApi to 2.0.0 + +The [Microsoft.OpenApi](https://www.nuget.org/packages/Microsoft.OpenApi/) library used for OpenAPI document generation in ASP.NET Core has been upgraded to version 2.0.0 (GA). +With this update to the GA version, no further breaking changes are expected in OpenAPI document generation. diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md b/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md index 91c864b39ea4..c76f692fc704 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md @@ -28,3 +28,8 @@ This configuration is done with directives in the project build file. The follow ``` We expect to include XML comments from a selected set of assemblies in the shared framework in future previews, to avoid the need for this configuration in most cases. + +#### Unified handling of documentation IDs in OpenAPI XML comment generator + +XML documentation comments from referenced assemblies are correctly merged even when their documentation IDs include return type suffixes. As a result, all valid XML comments are reliably included in generated OpenAPI documentation, improving documentation accuracy and completeness for APIs using referenced assemblies. + From bd26adf886851c16bd3369a594c7c9d1f6fb0a4d Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 11 Aug 2025 14:35:00 -0700 Subject: [PATCH 2/8] Removed dupe openAPI 2 .md file --- .../aspnetcore-10/includes/microsoft-openapi-v2upgrade.md | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md b/aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md deleted file mode 100644 index 327f34b990ce..000000000000 --- a/aspnetcore/release-notes/aspnetcore-10/includes/microsoft-openapi-v2upgrade.md +++ /dev/null @@ -1,4 +0,0 @@ -### Upgrade Microsoft.OpenApi to 2.0.0 - -The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation has been upgraded to v2.0.0 (GA). -With the update to the GA version of this package, no further breaking changes are expected in the OpenAPI document generation. From ccfbb700f10b53e92378491502672c8bd4391a0f Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 11 Aug 2025 14:41:56 -0700 Subject: [PATCH 3/8] Fixed link --- .../aspnetcore-10/includes/responseDescProducesResponseType.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md index 3855f82de9e2..1c043ca6d121 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md @@ -17,7 +17,7 @@ The following OpenAPI response and description are generated: "content": { ``` -This functionality is supported in both [API controllers](/aspnet/core/web-api#apicontroller-attribute) and [Minimal APIs](/aspnet/core/fundamentals/minimal-apis). For Minimal APIs, the `Description` property is correctly set even when the attribute’s type and the inferred return type aren't an exact match. +This functionality is supported in both [API controllers](~/web-api.md#apicontroller-attribute.md#apicontroller-attribute) and [Minimal APIs](~/fundamentals/minimal-apis.md). For Minimal APIs, the `Description` property is correctly set even when the attribute’s type and the inferred return type aren't an exact match. [Community contribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏 From e536595bbd4ee82cb5ff1b7ed1575e17045e7cf5 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 11 Aug 2025 14:56:32 -0700 Subject: [PATCH 4/8] revert respoinseDescProducesResponseType.md changes since a different PR is handling that --- .../includes/responseDescProducesResponseType.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md index 1c043ca6d121..29eb865527c6 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md @@ -1,6 +1,6 @@ -### Response description on ProducesResponseType for API controllers and Minimal APIs +### Response description on ProducesResponseType for API controllers -The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute) attributes now accept an optional string parameter, `Description`, that sets the description of the response. Here's an example: +The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute) attributes now accept an optional string parameter, `Description`, that will set the description of the response. Here's an example: ```csharp [HttpGet(Name = "GetWeatherForecast")] @@ -8,7 +8,9 @@ The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1 Description = "The weather forecast for the next 5 days.")] public IEnumerable Get() { -The following OpenAPI response and description are generated: +``` + +And the generated OpenAPI: ```json "responses": { @@ -16,8 +18,6 @@ The following OpenAPI response and description are generated: "description": "The weather forecast for the next 5 days.", "content": { ``` - -This functionality is supported in both [API controllers](~/web-api.md#apicontroller-attribute.md#apicontroller-attribute) and [Minimal APIs](~/fundamentals/minimal-apis.md). For Minimal APIs, the `Description` property is correctly set even when the attribute’s type and the inferred return type aren't an exact match. - +[Minimal APIs](https://github.com/dotnet/aspnetcore/issues/58724) currently don't support `ProducesResponseType`. [Community contribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏 From 2a521828f5a64634963565675898db9eb3183be9 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 11 Aug 2025 15:19:56 -0700 Subject: [PATCH 5/8] Added enahnced validation --- .../includes/enhance-validation-classes-records.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md b/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md new file mode 100644 index 000000000000..00c41141b9f6 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md @@ -0,0 +1,5 @@ +### Enhanced validation for classes and records + +Validation attributes can now be applied to both classes and records, with consistent code generation and validation behavior. This enhancement improves flexibility when designing models using records in ASP.NET Core applications. + +Community contribution: Thanks to [@marcominerva](https://github.com/marcominerva)! \ No newline at end of file From 97b0ff3b1a9be1a515222634395f55095318fb91 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 12 Aug 2025 10:08:04 -0700 Subject: [PATCH 6/8] Update aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .../includes/enhance-validation-classes-records.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md b/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md index 00c41141b9f6..13b1db1b8a63 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md @@ -1,5 +1,5 @@ ### Enhanced validation for classes and records -Validation attributes can now be applied to both classes and records, with consistent code generation and validation behavior. This enhancement improves flexibility when designing models using records in ASP.NET Core applications. +Validation attributes can now be applied to both classes and records with consistent code generation and validation behavior. This enhancement improves flexibility when designing models using records in ASP.NET Core apps. Community contribution: Thanks to [@marcominerva](https://github.com/marcominerva)! \ No newline at end of file From 6562bdb423ed2c6f9da2d9a1c40d9409c0d70f0e Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 12 Aug 2025 10:08:20 -0700 Subject: [PATCH 7/8] Update aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .../aspnetcore-10/includes/upgrade-microsoft-openapi-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md b/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md index 3d495db080bd..a34020114280 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md @@ -1,4 +1,4 @@ ### Upgrade Microsoft.OpenApi to 2.0.0 -The [Microsoft.OpenApi](https://www.nuget.org/packages/Microsoft.OpenApi/) library used for OpenAPI document generation in ASP.NET Core has been upgraded to version 2.0.0 (GA). +The [`Microsoft.OpenApi`](https://www.nuget.org/packages/Microsoft.OpenApi/) library used for OpenAPI document generation in ASP.NET Core has been upgraded to version 2.0.0 (GA). With this update to the GA version, no further breaking changes are expected in OpenAPI document generation. From 709f377544df7a0e80bc70c7c303dd0e918c794f Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 12 Aug 2025 10:08:29 -0700 Subject: [PATCH 8/8] Update aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .../aspnetcore-10/includes/xml-comment-generator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md b/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md index c76f692fc704..935ecb21f777 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/xml-comment-generator.md @@ -27,7 +27,7 @@ This configuration is done with directives in the project build file. The follow ``` -We expect to include XML comments from a selected set of assemblies in the shared framework in future previews, to avoid the need for this configuration in most cases. +We expect to include XML comments from a selected set of assemblies in the shared framework in future previews to avoid the need for this configuration in most cases. #### Unified handling of documentation IDs in OpenAPI XML comment generator