You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: aspnetcore/blazor/forms/index.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -243,7 +243,7 @@ The <xref:Microsoft.AspNetCore.Components.Forms.EditForm> provides the following
243
243
244
244
## Clear a form or field
245
245
246
-
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:
246
+
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:
247
247
248
248
```razor
249
249
<button @onclick="ClearForm">Clear form</button>
@@ -368,7 +368,7 @@ To disable enhanced form handling:
368
368
* 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"`).
369
369
* For an HTML `<form>`, remove the `data-enhance` attribute from form element (or set it to `false`: `data-enhance="false"`).
370
370
371
-
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.
371
+
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.
372
372
373
373
In the following example, the content of the `<div>` element is updated dynamically by a script when the page loads:
Copy file name to clipboardExpand all lines: aspnetcore/fundamentals/openapi/aspnetcore-openapi.md
+40-26
Original file line number
Diff line number
Diff line change
@@ -5,21 +5,43 @@ description: Learn how to generate and customize OpenAPI documents in an ASP.NET
5
5
ms.author: safia
6
6
monikerRange: '>= aspnetcore-6.0'
7
7
ms.custom: mvc
8
-
ms.date: 2/23/2025
8
+
ms.date: 3/18/2025
9
9
uid: fundamentals/openapi/aspnetcore-openapi
10
10
---
11
11
# Generate OpenAPI documents
12
12
13
-
:::moniker range=">= aspnetcore-9.0"
13
+
:::moniker range=">= aspnetcore-10.0"
14
14
15
15
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:
16
16
17
+
* Support for generating [OpenAPI version 3.1] documents.
18
+
* Support for [JSON Schema draft 2020-12].
17
19
* Support for generating OpenAPI documents at run time and accessing them via an endpoint on the app.
18
20
* Support for "transformer" APIs that allow modifying the generated document.
19
21
* Support for generating multiple OpenAPI documents from a single app.
20
22
* Takes advantage of JSON schema support provided by [`System.Text.Json`](/dotnet/api/system.text.json).
21
23
* Is compatible with native AoT.
22
24
25
+
[OpenAPI version 3.1]: https://spec.openapis.org/oas/v3.1.1.html
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):
When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item.
39
+
40
+
```xml
41
+
<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.1 document. -->
Install the `Microsoft.AspNetCore.OpenApi` package:
@@ -56,6 +78,16 @@ Launch the app and navigate to `https://localhost:<port>/openapi/v1.json` to vie
56
78
57
79
The following sections demonstrate how to customize OpenAPI document generation.
58
80
81
+
### Generate OpenAPI document in YAML format
82
+
83
+
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:
84
+
85
+
```csharp
86
+
app.MapOpenApi("/openapi/{documentName}.yaml");
87
+
```
88
+
89
+
Generating penAPI documents in YAML format at build time is currently not supported, but planned in a future preview.
90
+
59
91
### Customize the OpenAPI document name
60
92
61
93
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
81
113
82
114
### Customize the OpenAPI version of a generated document
83
115
84
-
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:
116
+
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:
Copy file name to clipboardExpand all lines: aspnetcore/fundamentals/openapi/include-metadata.md
+98
Original file line number
Diff line number
Diff line change
@@ -493,6 +493,8 @@ of the property in the schema.
493
493
494
494
### type and format
495
495
496
+
:::moniker range="< aspnetcore-10.0"
497
+
496
498
The JSON Schema library maps standard C# types to OpenAPI `type` and `format` as follows:
497
499
498
500
| C# Type | OpenAPI `type`| OpenAPI `format`|
@@ -520,6 +522,79 @@ Note that object and dynamic types have _no_ type defined in the OpenAPI because
520
522
521
523
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`.
522
524
525
+
:::moniker-end
526
+
527
+
:::moniker range=">= aspnetcore-10.0"
528
+
529
+
#### Numeric types
530
+
531
+
The JSON Schema library maps standard C# numeric types to OpenAPI `type` and `format` based on the
532
+
<xref:System.Text.Json.JsonSerializerOptions.NumberHandling> property of the <xref:System.Text.Json.JsonSerializerOptions>
533
+
used in the app. In ASP.NET Core Web API apps, the default value of this property is `JsonNumberHandling.AllowReadingFromString`.
534
+
535
+
When the <xref:System.Text.Json.JsonSerializerOptions.NumberHandling> property is set to `JsonNumberHandling.AllowReadingFromString`, the numeric types are mapped as follows:
536
+
537
+
| C# Type | OpenAPI `type`| OpenAPI `format`| Other assertions |
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.
558
+
559
+
When the <xref:System.Text.Json.JsonSerializerOptions.NumberHandling> property is set to `JsonNumberHandling.Strict`, the numeric types are mapped as follows:
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.
600
675
601
676
#### nullable
602
677
678
+
:::moniker range="< aspnetcore-10.0"
679
+
603
680
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.
604
681
682
+
:::moniker-end
683
+
:::moniker range=">= aspnetcore-10.0"
684
+
685
+
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.
686
+
687
+
For example, a C# property defined as `string?` is represented in the generated schema as:
688
+
689
+
```json
690
+
"nullableString": {
691
+
"description": "A property defined as string?",
692
+
"type": [
693
+
"null",
694
+
"string"
695
+
]
696
+
},
697
+
```
698
+
699
+
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.
700
+
701
+
:::moniker-end
702
+
605
703
#### additionalProperties
606
704
607
705
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.
0 commit comments