OpenApi 3.1 /1 (#35242)

* OpenApi 3.1 /1

* fix stuff

* fix stuff

* fix stuff

* fix stuff

Author: Rick-Anderson

aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

@@ -5,7 +5,7 @@ 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
@@ -14,12 +14,34 @@ uid: fundamentals/openapi/aspnetcore-openapi
 
 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:
@@ -81,12 +103,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;
 });
 ```
 

aspnetcore/fundamentals/openapi/includes/aspnetcore-openapi9.md

@@ -263,10 +263,10 @@ var app = builder.Build();
 + app.MapOpenApi();
 ```
 
-:::moniker-end
-
 Publish the app.
 
 ```console
 dotnet publish
 ```
+
+:::moniker-end