WN: P1

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

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
     <!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.0 document. -->
     <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>
 ```
 
+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.

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<WeatherForecast> 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! 🙏 
+[Community contribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏