WN: v10 Prev 4: OpenApiSchemas in transformers

aspnetcore/release-notes/aspnetcore-10.0.md

@@ -53,6 +53,8 @@ This section describes new features for OpenAPI.
 
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/webapiaotTemplateAddedOpenAPI.md)]
 
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md)]
+
 ## Authentication and authorization
 
 This section describes new features for authentication and authorization.

aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md

@@ -1,42 +1,15 @@
 ### Support for generating OpenApiSchemas in transformers
 <!-- https://github.com/dotnet/aspnetcore/pull/61050 -->
 
-Developers can now generate a schema for a C# type, using the same logic as ASP.NET Core OpenAPI document generation,
-and add it to the OpenAPI document. The schema can then be referenced from elsewhere in the OpenAPI document.
+Developers can now generate a schema for a C# type using the same logic as ASP.NET Core OpenAPI document generation and add it to the OpenAPI document. The schema can then be referenced from elsewhere in the OpenAPI document.
 
-The context passed to document, operation, and schema transformers now has a `GetOrCreateSchemaAsync` method that can be used to generate a schema for a type.
+The context passed to document, operation, and schema transformers includes a new `GetOrCreateSchemaAsync` method that can be used to generate a schema for a type.
 This method also has an optional `ApiParameterDescription` parameter to specify additional metadata for the generated schema.
 
 To support adding the schema to the OpenAPI document, a `Document` property has been added to the Operation and Schema transformer contexts. This allows any transformer to add a schema to the OpenAPI document using the document's `AddComponent` method.
 
 #### Example
 
-To use this feature in an document, operation, or schema transformer, create the schema using the `GetOrCreateSchemaAsync` method provided in the context
-and add it to the OpenAPI document using the document's `AddComponent` method.
+To use this feature in a document, operation, or schema transformer, create the schema using the `GetOrCreateSchemaAsync` method provided in the context and add it to the OpenAPI document using the document's `AddComponent` method.
 
-<!-- In the docs, highlight the lines with the call to "GetOrCreateSchemaAsync" and "AddComponent" -->
-```csharp
-builder.Services.AddOpenApi(options =>
-{
-    options.AddOperationTransformer(async (operation, context, cancellationToken) =>
-    {
-        // Generate schema for error responses
-        var errorSchema = await context.GetOrCreateSchemaAsync(typeof(ProblemDetails), null, cancellationToken);
-        context.Document?.AddComponent("Error", errorSchema);
-
-        operation.Responses ??= new OpenApiResponses();
-        // Add a "4XX" response to the operation with the newly created schema
-        operation.Responses["4XX"] = new OpenApiResponse
-        {
-            Description = "Bad Request",
-            Content = new Dictionary<string, OpenApiMediaType>
-            {
-                ["application/problem+json"] = new OpenApiMediaType
-                {
-                    Schema = new OpenApiSchemaReference("Error", context.Document)
-                }
-            }
-        };
-    });
-});
-```
+:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_Generate_OpenApiSchemas_for_type" highlight="6-7":::

aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs

@@ -1,3 +1,6 @@
+#define SCHEMA_IN_TRANSFORMER_EXAMPLE     //YAML_EXAMPLE   //SCHEMA_IN_TRANSFORMER_EXAMPLE
+#if YAML_EXAMPLE
+
 var builder = WebApplication.CreateBuilder(args);
 
 // Add services to the container.
@@ -6,7 +9,7 @@
 // <snippet_DefaultOpenApiVersion>
 builder.Services.AddOpenApi(options =>
 {
-    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
+    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1;
 });
 // </snippet_DefaultOpenApiVersion>
 
@@ -27,3 +30,54 @@
 app.MapControllers();
 
 app.Run();
+
+#elif SCHEMA_IN_TRANSFORMER_EXAMPLE
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add services to the container.
+builder.Services.AddControllers();
+// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
+// <snippet_Generate_OpenApiSchemas_for_type>
+builder.Services.AddOpenApi(options =>
+{
+    options.AddOperationTransformer(async (operation, context, cancellationToken) =>
+    {
+        // Generate schema for error responses
+        var errorSchema = await context.GetOrCreateSchemaAsync(typeof(ProblemDetails), null, cancellationToken);
+        context.Document?.AddComponent("Error", errorSchema);
+
+        operation.Responses ??= new OpenApiResponses();
+        // Add a "4XX" response to the operation with the newly created schema
+        operation.Responses["4XX"] = new OpenApiResponse
+        {
+            Description = "Bad Request",
+            Content = new Dictionary<string, OpenApiMediaType>
+            {
+                ["application/problem+json"] = new OpenApiMediaType
+                {
+                    Schema = new OpenApiSchemaReference("Error", context.Document)
+                }
+            }
+        };
+    });
+});
+// </snippet_Generate_OpenApiSchemas_for_type>
+
+var app = builder.Build();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi("/openapi/{documentName}.yaml");
+}
+
+app.UseHttpsRedirection();
+
+app.UseAuthorization();
+
+app.MapControllers();
+
+app.Run();
+
+#endif

aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj

@@ -6,13 +6,13 @@
 		<Nullable>enable</Nullable>
 		<ImplicitUsings>enable</ImplicitUsings>
 		<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
-		<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.0 document. -->
-		<OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>
+		<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.1 document. -->
+		<OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_1</OpenApiGenerateDocumentsOptions>
 	</PropertyGroup>
 	<!-- </snippet_ConfigBuildTimeOpenApiDocVersion> -->
 
 	<ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.3.25172.1" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.4.24272.1" />
     </ItemGroup>
 
 </Project>