Merge to Live

aspnetcore/blazor/forms/index.md

@@ -243,7 +243,7 @@ The <xref:Microsoft.AspNetCore.Components.Forms.EditForm> provides the following
 
 ## Clear a form or field
 
-Reset a form by clearing its model back its default state, which can be performed inside or outside of an <xref:Microsoft.AspNetCore.Components.Forms.EditForm>'s markup:
+Reset a form by clearing its model back to its default state, which can be performed inside or outside of an <xref:Microsoft.AspNetCore.Components.Forms.EditForm>'s markup:
 
 ```razor
 <button @onclick="ClearForm">Clear form</button>
@@ -368,7 +368,7 @@ To disable enhanced form handling:
 * For an <xref:Microsoft.AspNetCore.Components.Forms.EditForm>, remove the <xref:Microsoft.AspNetCore.Components.Forms.EditForm.Enhance%2A> parameter from the form element (or set it to `false`: `Enhance="false"`).
 * For an HTML `<form>`, remove the `data-enhance` attribute from form element (or set it to `false`: `data-enhance="false"`).
 
-Blazor's enhanced navigation and form handing may undo dynamic changes to the DOM if the updated content isn't part of the server rendering. To preserve the content of an element, use the `data-permanent` attribute.
+Blazor's enhanced navigation and form handling may undo dynamic changes to the DOM if the updated content isn't part of the server rendering. To preserve the content of an element, use the `data-permanent` attribute.
 
 In the following example, the content of the `<div>` element is updated dynamically by a script when the page loads:
 

aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

@@ -5,21 +5,43 @@ description: Learn how to generate and customize OpenAPI documents in an ASP.NET
 ms.author: safia
 monikerRange: '>= aspnetcore-6.0'
 ms.custom: mvc
-ms.date: 2/23/2025
+ms.date: 3/18/2025
 uid: fundamentals/openapi/aspnetcore-openapi
 ---
 # Generate OpenAPI documents
 
-:::moniker range=">= aspnetcore-9.0"
+:::moniker range=">= aspnetcore-10.0"
 
 The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) package provides built-in support for OpenAPI document generation in ASP.NET Core. The package provides the following features:
 
+* Support for generating [OpenAPI version 3.1] documents.
+* Support for [JSON Schema draft 2020-12].
 * Support for generating OpenAPI documents at run time and accessing them via an endpoint on the app.
 * Support for "transformer" APIs that allow modifying the generated document.
 * Support for generating multiple OpenAPI documents from a single app.
 * Takes advantage of JSON schema support provided by [`System.Text.Json`](/dotnet/api/system.text.json).
 * Is compatible with native AoT.
 
+[OpenAPI version 3.1]: https://spec.openapis.org/oas/v3.1.1.html
+[JSON Schema draft 2020-12]: https://json-schema.org/specification-links#2020-12
+
+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 =>
+{
+    // Specify the OpenAPI version to use.
+    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
+});
+```
+
+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.1 document. -->
+    <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_1</OpenApiGenerateDocumentsOptions>
+```
+
 ## Package installation
 
 Install the `Microsoft.AspNetCore.OpenApi` package:
@@ -56,6 +78,16 @@ Launch the app and navigate to `https://localhost:<port>/openapi/v1.json` to vie
 
 The following sections demonstrate how to customize OpenAPI document generation.
 
+### Generate OpenAPI document in YAML format
+
+The OpenAPI document can be generated in either JSON or YAML format. By default, the OpenAPI document is generated in JSON format. To generate the 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");
+```
+
+Generating penAPI documents in YAML format at build time is currently not supported, but planned in a future preview.
+
 ### Customize the OpenAPI document name
 
 Each OpenAPI document in an app has a unique name. The default document name that is registered is `v1`.
@@ -81,12 +113,12 @@ GET http://localhost:5000/openapi/internal.json
 
 ### Customize the OpenAPI version of a generated document
 
-By default, OpenAPI document generation creates a document that is compliant with [v3.0 of the OpenAPI specification](https://spec.openapis.org/oas/v3.0.0). The following code demonstrates how to modify the default version of the OpenAPI document:
+By default, OpenAPI document generation creates a document that is compliant with [OpenAPI version 3.1](https://spec.openapis.org/oas/v3.1.1.html). The following code demonstrates how to modify the default version of the OpenAPI document:
 
 ```csharp
 builder.Services.AddOpenApi(options =>
 {
-    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
+    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
 });
 ```
 
@@ -259,32 +291,14 @@ Create a new ASP.NET Core Web API (Native AOT) project.
 dotnet new webapiaot
 ```
 
-:::moniker-end
-
-:::moniker range="= aspnetcore-9.0"
-
-Add the Microsoft.AspNetCore.OpenAPI package.
-
-```console
-dotnet add package Microsoft.AspNetCore.OpenApi
-```
-
-Update `Program.cs` to enable generating OpenAPI documents.
-
-```diff
-+ builder.Services.AddOpenApi();
-
-var app = builder.Build();
-
-+ app.MapOpenApi();
-```
-
-:::moniker-end
-
 Publish the app.
 
 ```console
 dotnet publish
 ```
 
+:::moniker-end
+
 [!INCLUDE[](~/fundamentals/openapi/includes/aspnetcore-openapi6-8.md)]
+
+[!INCLUDE[](~/fundamentals/openapi/includes/aspnetcore-openapi9.md)]

aspnetcore/fundamentals/openapi/include-metadata.md

@@ -493,6 +493,8 @@ of the property in the schema.
 
 ### type and format
 
+:::moniker range="< aspnetcore-10.0"
+
 The JSON Schema library maps standard C# types to OpenAPI `type` and `format` as follows:
 
 | C# Type        | OpenAPI `type` | OpenAPI `format` |
@@ -520,6 +522,79 @@ Note that object and dynamic types have _no_ type defined in the OpenAPI because
 
 The `type` and `format` can also be set with a [Schema Transformer](xref:fundamentals/openapi/customize-openapi#use-schema-transformers). For example, you may want the `format` of decimal types to be `decimal` instead of `double`.
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-10.0"
+
+#### Numeric types
+
+The JSON Schema library maps standard C# numeric types to OpenAPI `type` and `format` based on the
+<xref:System.Text.Json.JsonSerializerOptions.NumberHandling> property of the <xref:System.Text.Json.JsonSerializerOptions>
+used in the app. In ASP.NET Core Web API apps, the default value of this property is `JsonNumberHandling.AllowReadingFromString`.
+
+When the <xref:System.Text.Json.JsonSerializerOptions.NumberHandling> property is set to `JsonNumberHandling.AllowReadingFromString`, the numeric types are mapped as follows:
+
+| C# Type        | OpenAPI `type`   | OpenAPI `format` | Other assertions               |
+| -------------- | ---------------- | ---------------- | ------------------------------ |
+| int            | [integer,string] | int32            | pattern `<digits>` |
+| long           | [integer,string] | int64            | pattern `<digits>` |
+| short          | [integer,string] | int16            | pattern `<digits>` |
+| byte           | [integer,string] | uint8            | pattern `<digits>` |
+| float          | [number,string]  | float            | pattern `<digits with decimal >` |
+| double         | [number,string]  | double           | pattern `<digits with decimal >` |
+| decimal        | [number,string]  | double           | pattern `<digits with decimal >` |
+
+<!--
+| int            | [integer,string] | int32            | pattern `<digits>` |  pattern: `"^-?(?:0|[1-9]\\d*)$"`
+| long           | [integer,string] | int64            | pattern `<digits>` |                                 
+| short          | [integer,string] | int16            | pattern `<digits>` |                                  
+| byte           | [integer,string] | uint8            | pattern `<digits>` |                                  
+| float          | [number,string]  | float            | pattern `<digits with decimal >` |   pattern: `"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$"`
+| double         | [number,string]  | double           | pattern `<digits with decimal >` |                                  
+| decimal        | [number,string]  | double           | pattern `<digits with decimal >` |   pattern: `"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$"`
+ -->
+
+If the app is configured to produce OpenAPI 3.0 or OpenAPI v2 documents, where the `type` field cannot have an array value, the `type` field is dropped.
+
+When the <xref:System.Text.Json.JsonSerializerOptions.NumberHandling> property is set to `JsonNumberHandling.Strict`, the numeric types are mapped as follows:
+
+| C# Type        | OpenAPI `type` | OpenAPI `format` |
+| -------------- | -------------- | ---------------- |
+| int            | integer        | int32            |
+| long           | integer        | int64            |
+| short          | integer        | int16            |
+| byte           | integer        | uint8            |
+| float          | number         | float            |
+| double         | number         | double           |
+| decimal        | number         | double           |
+
+#### String types
+
+The following table shows how C# types map to `string` type properties in the generated OpenAPI document:
+
+| C# Type        | OpenAPI `type` | OpenAPI `format` | Other assertions               |
+| -------------- | -------------- | ---------------- | ------------------------------ |
+| string         | string         |                  | |
+| char           | string         | char             | minLength: 1, maxLength: 1 |
+| byte[]         | string         | byte             | |
+| DateTimeOffset | string         | date-time        | |
+| DateOnly       | string         | date             | |
+| TimeOnly       | string         | time             | |
+| Uri            | string         | uri              | |
+| Guid           | string         | uuid             | |
+
+#### Other types
+
+Other C# types are represented in the generated OpenAPI document as shown in the following table:
+
+| C# Type        | OpenAPI `type` | OpenAPI `format` |
+| -------------- | -------------- | ---------------- |
+| bool           | boolean        |                  |
+| object         | _omitted_      |                  |
+| dynamic        | _omitted_      |                  |
+
+:::moniker-end
+
 ### Use attributes to add metadata
 
 ASP.NET uses metadata from attributes on class or record properties to set metadata on the corresponding properties of the generated schema.
@@ -600,8 +675,31 @@ An enum type without a  [`[JsonConverter]`](xref:System.Text.Json.Serialization.
 
 #### nullable
 
+:::moniker range="< aspnetcore-10.0"
+
 Properties defined as a nullable value or reference type have `nullable: true` in the generated schema. This is consistent with the default behavior of the <xref:System.Text.Json> deserializer, which accepts `null` as a valid value for a nullable property.
 
+:::moniker-end
+:::moniker range=">= aspnetcore-10.0"
+
+Properties defined as a nullable value or reference type appear in the generated schema with a `type` keyword whose value is an array that includes `null` as one of the types. This is consistent with the default behavior of the <xref:System.Text.Json> deserializer, which accepts `null` as a valid value for a nullable property.
+
+For example, a C# property defined as `string?` is represented in the generated schema as:
+
+```json
+  "nullableString": {
+    "description": "A property defined as string?",
+    "type": [
+      "null",
+      "string"
+    ]
+  },
+```
+
+If the app is configured to produce OpenAPI v3.0 or OpenAPI v2 documents, nullable value or reference types have `nullable: true` in the generated schema because these OpenAPI versions do not allow the `type` field to be an array.
+
+:::moniker-end
+
 #### additionalProperties
 
 Schemas are generated without an `additionalProperties` assertion by default, which implies the default of `true`. This is consistent with the default behavior of the <xref:System.Text.Json> deserializer, which silently ignores additional properties in a JSON object.