From 01f0a3799e5ab1b9f4c522907362a2f78e41e9b1 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 14:59:55 -1000 Subject: [PATCH 1/7] WN: P1 --- aspnetcore/release-notes/aspnetcore-10.0.md | 7 ++++ .../aspnetcore-10/includes/openApi.md | 42 +++++++++---------- .../responseDescProducesResponseType.md | 8 ++-- 3 files changed, 30 insertions(+), 27 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index c3927a3fd154..38c355323870 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/aspnetcore/release-notes/aspnetcore-10.0.md @@ -33,6 +33,11 @@ This section describes new features for minimal APIs. This section describes new features for OpenAPI. +[!INCLUDE[](~/release-notes/aspnetcore-10/includes/openApi.md)] + + +[!INCLUDE[](~/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md)] + ## Authentication and authorization This section describes new features for authentication and authorization. @@ -41,4 +46,6 @@ This section describes new features for authentication and authorization. This section describes miscellaneous new features in ASP.NET Core 10.0. +[!INCLUDE[](~/release-notes/aspnetcore-10/includes/testAppsTopLevel.md)] + ## Related content diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 13ab72d7e097..34b8bdb1739f 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -1,7 +1,5 @@ ### OpenAPI 3.1 support -https://github.com/dotnet/aspnetcore/pull/59480 -https://github.com/dotnet/aspnetcore/pull/60002 ASP.NET Core has added support for generating [OpenAPI version 3.1] documents in .NET 10. Despite the minor version bump, OpenAPI 3.1 is a significant update to the OpenAPI specification, @@ -11,11 +9,12 @@ in particular with full support for [JSON Schema draft 2020-12]. [JSON Schema draft 2020-12]: https://json-schema.org/specification-links#2020-12 Some of the changes you will see in the generated OpenAPI document include: -- Nullable types will no longer have the `nullable: true` property in the schema, and instead will have a `type` keyword whose value is an array that includes `null` as one of the types. -With this feature, the default OpenAPI version for generated documents will be 3.1, but you can easily change this -by explicitly setting the `OpenApiVersion` property of the `OpenApiOptions` in the `configureOptions` delegate -parameter of `AddOpenApi`. +- Nullable types no longer have the `nullable: true` property in the schema. +- Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types. + +With this feature, the default OpenAPI version for generated documents will be `3.1` . You can easily change the version +by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion?view=aspnetcore-9.0) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions?view=aspnetcore-9.0) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi?view=aspnetcore-9.0). ```csharp builder.Services.AddOpenApi(options => @@ -25,21 +24,21 @@ builder.Services.AddOpenApi(options => }); ``` -If you are generating the OpenAPI document at build time, you can select the OpenAPI version by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item. +When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item. ```xml --openapi-version OpenApi3_0 ``` +OpenAPI 3.1 support was primarly added in the following this [PR](https://github.com/dotnet/aspnetcore/pull/59480). + + ### Breaking changes -Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. -This new version has some breaking changes from the previous version, and this may impact your applications -if you have any document, operation, or schema transformers. -Perhaps the most significant change is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. -If your transformers use `OpenApiAny`, you will need to update them to use `JsonNode` instead. -For example, a schema transformer to add an example in .NET 9 might look like this: +Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers. + +One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly.If your transformers use `OpenApiAny`, you will need to update them to use `JsonNode` instead. For example, a schema transformer to add an example in .NET 9 might look like the following: ```csharp options.AddSchemaTransformer((schema, context, cancellationToken) => @@ -58,7 +57,7 @@ For example, a schema transformer to add an example in .NET 9 might look like th }); ``` -In .NET 10 the transformer to do the same task will look like this: +In .NET 10 the transformer to do the same task will look like the following: ```csharp options.AddSchemaTransformer((schema, context, cancellationToken) => @@ -77,22 +76,21 @@ In .NET 10 the transformer to do the same task will look like this: }); ``` -Note that these changes will be necessary even if you congfigure the OpenAPI version to 3.0. +Note that these changes are necessary even when only congfiguring the OpenAPI version to 3.0. ### OpenAPI in Yaml https://github.com/dotnet/aspnetcore/pull/58616 -ASP.NET now supports serving the generated OpenAPI document in YAML format. -YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred. -YAML also supports multi-line strings, which can be useful for long descriptions. +ASP.NET now supports serving the generated OpenAPI document in YAML format. YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred. YAML also supports multi-line strings, which can be useful for long descriptions. -To configure your application to serve the generated OpenAPI document in YAML format, -specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in this example: +To configure an app to serve the generated OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example: ```csharp app.MapOpenApi("/openapi/{documentName}.yaml"); ``` -Support for YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint. -Support for generating OpenAPI documents in YAML format at build time will be added in a future preview. +Support for: + +* YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint. +* Generating OpenAPI documents in YAML format at build time will be added in a future preview. diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md index 3dd6d3874773..b6ccff00829d 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md @@ -1,8 +1,6 @@ ### Response description on ProducesResponseType -https://github.com/dotnet/aspnetcore/pull/58193 - -The ProducesAttribute, ProducesResponseTypeAttribute, and ProducesDefaultResponseType 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?view=aspnetcore-9.0), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1?view=aspnetcore-9.0), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute?view=aspnetcore-9.0) attributes now accept an optional string parameter, `Description`, that will set the description of the response. Here's an example: ```csharp [HttpGet(Name = "GetWeatherForecast")] @@ -11,7 +9,7 @@ public IEnumerable Get() { ``` -And the generated OpenAPI will be +And the generated OpenAPI: ```json "responses": { @@ -20,4 +18,4 @@ And the generated OpenAPI will be "content": { ``` -Community contribution! 🙏 \ No newline at end of file +[Community contribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏 From 737a1ea5f12afeae2e90f5ea35f9463b11dc7819 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 15:14:26 -1000 Subject: [PATCH 2/7] WN: P1 --- aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 34b8bdb1739f..c992cf04a898 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -94,3 +94,5 @@ Support for: * YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint. * Generating OpenAPI documents in YAML format at build time will be added in a future preview. + +See [this PR](https://github.com/dotnet/aspnetcore/pull/58616) which added support for serving the generated OpenAPI document in YAML format. \ No newline at end of file From 378bfcc14f7b7b463fa7490dd0a829256d8c53c7 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 15:21:44 -1000 Subject: [PATCH 3/7] WN: P1 --- .../includes/testAppsTopLevel.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md b/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md index 7894fdd0c15e..ac0d9402005f 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md @@ -1,17 +1,12 @@ ## Better support for testing apps with top-level statements -https://github.com/dotnet/aspnetcore/pull/58199 -https://github.com/dotnet/aspnetcore/pull/58482 +.NET 10 now has better support for testing apps that use top-level statements. Previously developers had to manually add `public partial class Program` to the `Program.cs` file so that the test project could reference the `Program class`. This is because the top-level statement feature in C# 9 generated a `Program class` that was declared as internal. -.NET 10 now has better support for testing apps that use top-level statements. -Previously developers had to manually add `public partial class Program` to the -Program.cs file so that the test project could reference the Program class. -This is because the top-level statement feature in C# 9 generated a Program class -that was declared as internal. +In .NET 10, a source generator is used to generate the `public partial class Program` declaration if the programmer did not declare it explicitly. In addition, an analyzer was added to detect when `public partial class Program` is declared explicitly and advise the developer to remove it. -In .NET 10, a source generator is used to generate the `public partial class Program` -declaration if the programmer did not declare it explicitly. In addition, an analyzer -was added to detect when `public partial class Program` is declared explicitly and -advise the developer to remove it. +![Image](https://github.com/user-attachments/assets/a37f0c81-a58a-453f-8da5-fa49356ca180) -![Image](https://github.com/user-attachments/assets/a37f0c81-a58a-453f-8da5-fa49356ca180) \ No newline at end of file +The following PRs contribited to this feature: + +* [PR 58199](https://github.com/dotnet/aspnetcore/pull/58199) +* [PR 58482](https://github.com/dotnet/aspnetcore/pull/58482) \ No newline at end of file From 606c6e63f7289e769a9f1aeeb347ecc6b006440c Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 15:24:10 -1000 Subject: [PATCH 4/7] WN: P1 --- aspnetcore/release-notes/aspnetcore-10.0.md | 1 - aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 4 +--- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index 38c355323870..f37174acaf77 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/aspnetcore/release-notes/aspnetcore-10.0.md @@ -35,7 +35,6 @@ This section describes new features for OpenAPI. [!INCLUDE[](~/release-notes/aspnetcore-10/includes/openApi.md)] - [!INCLUDE[](~/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md)] ## Authentication and authorization diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index c992cf04a898..5d0ca75ce95d 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -1,6 +1,5 @@ ### OpenAPI 3.1 support - ASP.NET Core has added support for generating [OpenAPI version 3.1] documents in .NET 10. Despite the minor version bump, OpenAPI 3.1 is a significant update to the OpenAPI specification, in particular with full support for [JSON Schema draft 2020-12]. @@ -33,8 +32,7 @@ When generating the OpenAPI document at build time, the OpenAPI version can be s OpenAPI 3.1 support was primarly added in the following this [PR](https://github.com/dotnet/aspnetcore/pull/59480). - -### Breaking changes +### OpenAPI 3.1 breaking changes Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers. From 3e65e28571f56ec3db42105f4f941ca505f65230 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 15:29:21 -1000 Subject: [PATCH 5/7] WN: P1 --- aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 7 +++---- .../includes/responseDescProducesResponseType.md | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 5d0ca75ce95d..6a1a1c8e49d7 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -12,8 +12,7 @@ Some of the changes you will see in the generated OpenAPI document include: - Nullable types no longer have the `nullable: true` property in the schema. - Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types. -With this feature, the default OpenAPI version for generated documents will be `3.1` . You can easily change the version -by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion?view=aspnetcore-9.0) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions?view=aspnetcore-9.0) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi?view=aspnetcore-9.0). +With this feature, the default OpenAPI version for generated documents is`3.1` . The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi). ```csharp builder.Services.AddOpenApi(options => @@ -30,7 +29,7 @@ When generating the OpenAPI document at build time, the OpenAPI version can be s --openapi-version OpenApi3_0 ``` -OpenAPI 3.1 support was primarly added in the following this [PR](https://github.com/dotnet/aspnetcore/pull/59480). +OpenAPI 3.1 support was primarly added in the following [PR](https://github.com/dotnet/aspnetcore/pull/59480). ### OpenAPI 3.1 breaking changes @@ -91,6 +90,6 @@ app.MapOpenApi("/openapi/{documentName}.yaml"); Support for: * YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint. -* Generating OpenAPI documents in YAML format at build time will be added in a future preview. +* Generating OpenAPI documents in YAML format at build time isadded in a future preview. See [this PR](https://github.com/dotnet/aspnetcore/pull/58616) which added support for serving the generated OpenAPI document in YAML format. \ No newline at end of file diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md b/aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md index b6ccff00829d..c9602f685f2d 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 -The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1?view=aspnetcore-9.0), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1?view=aspnetcore-9.0), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute?view=aspnetcore-9.0) 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 will set the description of the response. Here's an example: ```csharp [HttpGet(Name = "GetWeatherForecast")] From 85c998ae30c7fae29e638a788b764a0bae3cf278 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 15:51:20 -1000 Subject: [PATCH 6/7] WN: P1 --- .../aspnetcore-10/includes/openApi.md | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 6a1a1c8e49d7..77a5ef96ffe2 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -12,7 +12,7 @@ Some of the changes you will see in the generated OpenAPI document include: - Nullable types no longer have the `nullable: true` property in the schema. - Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types. -With this feature, the default OpenAPI version for generated documents is`3.1` . The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi). +With this feature, the default OpenAPI version for generated documents is`3.1`. The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi). ```csharp builder.Services.AddOpenApi(options => @@ -35,7 +35,7 @@ OpenAPI 3.1 support was primarly added in the following [PR](https://github.com/ Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers. -One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly.If your transformers use `OpenApiAny`, you will need to update them to use `JsonNode` instead. For example, a schema transformer to add an example in .NET 9 might look like the following: +One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. For example, a schema transformer to add an example in .NET 9 might look like the following: ```csharp options.AddSchemaTransformer((schema, context, cancellationToken) => @@ -73,6 +73,30 @@ In .NET 10 the transformer to do the same task will look like the following: }); ``` +The following example shows the changes in diff format. + +```diff +options.AddSchemaTransformer((schema, context, cancellationToken) => +{ + if (context.JsonTypeInfo.Type == typeof(WeatherForecast)) + { +- schema.Example = new OpenApiObject ++ schema.Example = new JsonObject + { +- ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")), ++ ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"), +- ["temperatureC"] = new OpenApiInteger(0), ++ ["temperatureC"] = 0, +- ["temperatureF"] = new OpenApiInteger(32), ++ ["temperatureF"] = 32, +- ["summary"] = new OpenApiString("Bracing"), ++ []"summary"] = "Bracing", + }; + } + return Task.CompletedTask; +}); +``` + Note that these changes are necessary even when only congfiguring the OpenAPI version to 3.0. ### OpenAPI in Yaml From e60abd776812b3e7b318d95338f74fccde0a7584 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 14 Feb 2025 16:16:34 -1000 Subject: [PATCH 7/7] WN: P1 --- .../release-notes/aspnetcore-10/includes/openApi.md | 10 ++++------ .../aspnetcore-10/includes/testAppsTopLevel.md | 4 ++-- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 77a5ef96ffe2..b46662ac2c55 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -35,7 +35,7 @@ OpenAPI 3.1 support was primarly added in the following [PR](https://github.com/ Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers. -One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. For example, a schema transformer to add an example in .NET 9 might look like the following: +One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. For example, a schema transformer to add an example in .NET 9 might look like the following code: ```csharp options.AddSchemaTransformer((schema, context, cancellationToken) => @@ -54,7 +54,7 @@ One of the most significant changes is that the `OpenApiAny` class has been drop }); ``` -In .NET 10 the transformer to do the same task will look like the following: +In .NET 10 the transformer to do the same task will look like the following code: ```csharp options.AddSchemaTransformer((schema, context, cancellationToken) => @@ -101,8 +101,6 @@ Note that these changes are necessary even when only congfiguring the OpenAPI ve ### OpenAPI in Yaml -https://github.com/dotnet/aspnetcore/pull/58616 - ASP.NET now supports serving the generated OpenAPI document in YAML format. YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred. YAML also supports multi-line strings, which can be useful for long descriptions. To configure an app to serve the generated OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example: @@ -113,7 +111,7 @@ app.MapOpenApi("/openapi/{documentName}.yaml"); Support for: -* YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint. -* Generating OpenAPI documents in YAML format at build time isadded in a future preview. +- YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint. +- Generating OpenAPI documents in YAML format at build time isadded in a future preview. See [this PR](https://github.com/dotnet/aspnetcore/pull/58616) which added support for serving the generated OpenAPI document in YAML format. \ No newline at end of file diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md b/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md index ac0d9402005f..ae0911efb145 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/testAppsTopLevel.md @@ -8,5 +8,5 @@ In .NET 10, a source generator is used to generate the `public partial class Pro The following PRs contribited to this feature: -* [PR 58199](https://github.com/dotnet/aspnetcore/pull/58199) -* [PR 58482](https://github.com/dotnet/aspnetcore/pull/58482) \ No newline at end of file +- [PR 58199](https://github.com/dotnet/aspnetcore/pull/58199) +- [PR 58482](https://github.com/dotnet/aspnetcore/pull/58482) \ No newline at end of file