Add OpenAPI

Author: Rick-Anderson

aspnetcore/release-notes/aspnetcore-10.0.md

@@ -29,6 +29,57 @@ This section describes new features for SignalR.
 
 This section describes new features for minimal APIs.
 
+## OpenAPI
+
+This section describes new features for OpenAPI.
+
+### 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:
+
+```csharp
+    options.AddSchemaTransformer((schema, context, cancellationToken) =>
+    {
+        if (context.JsonTypeInfo.Type == typeof(WeatherForecast))
+        {
+            schema.Example = new OpenApiObject
+            {
+                ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")),
+                ["temperatureC"] = new OpenApiInteger(0),
+                ["temperatureF"] = new OpenApiInteger(32),
+                ["summary"] = new OpenApiString("Bracing"),
+            };
+        }
+        return Task.CompletedTask;
+    });
+```
+
+In .NET 10 the transformer to do the same task will look like this:
+
+```csharp
+    options.AddSchemaTransformer((schema, context, cancellationToken) =>
+    {
+        if (context.JsonTypeInfo.Type == typeof(WeatherForecast))
+        {
+            schema.Example = new JsonObject
+            {
+                ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"),
+                ["temperatureC"] = 0,
+                ["temperatureF"] = 32,
+                ["summary"] = "Bracing",
+            };
+        }
+        return Task.CompletedTask;
+    });
+```
+
+Note that these changes will be necessary even if you congfigure the OpenAPI version to 3.0.
+
 ## Authentication and authorization
 
 This section describes new features for authentication and authorization.