From 0881a64d1855ec09cf34443966ec7a8afe4d0af2 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Fri, 9 May 2025 17:22:02 -0700 Subject: [PATCH 1/6] WN: v10 Prev 4: OpenApiSchemas in transformers --- aspnetcore/release-notes/aspnetcore-10.0.md | 2 + .../includes/OpenApiSchemasInTransformers.md | 34 ++--------- .../samples/WebAppOpenAPI10/Program.cs | 56 ++++++++++++++++++- .../WebAppOpenAPI10/WebAppOpenAPI10.csproj | 11 ++-- 4 files changed, 68 insertions(+), 35 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index 2b821741f388..1f93d35fb443 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/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. diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md index 262267cd234e..b6e9eab3643c 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md @@ -1,42 +1,16 @@ ### Support for generating OpenApiSchemas in transformers -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 provided 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. -```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 - { - ["application/problem+json"] = new OpenApiMediaType - { - Schema = new OpenApiSchemaReference("Error", context.Document) - } - } - }; - }); -}); -``` \ No newline at end of file +:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_Generate_OpenApiSchemas_for_type" highlight="6-7"::: diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs index d6601275a9ef..f72a6aa44533 100644 --- a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs +++ b/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 @@ // builder.Services.AddOpenApi(options => { - options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0; + options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1; }); // @@ -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 +// +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 + { + ["application/problem+json"] = new OpenApiMediaType + { + Schema = new OpenApiSchemaReference("Error", context.Document) + } + } + }; + }); +}); +// + +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 diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj index bf00c497c4f4..980036af6279 100644 --- a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj @@ -6,13 +6,16 @@ enable enable true - - --openapi-version OpenApi3_0 + + --openapi-version OpenApi3_1 + + + - - + + From c6585eb5ddf6f07191cb2492b2a12e2792d8833d Mon Sep 17 00:00:00 2001 From: wadepickett Date: Fri, 9 May 2025 17:31:10 -0700 Subject: [PATCH 2/6] Remove include entry, will add later --- aspnetcore/release-notes/aspnetcore-10.0.md | 2 -- .../aspnetcore-10/includes/OpenApiSchemasInTransformers.md | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index 1f93d35fb443..2b821741f388 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/aspnetcore/release-notes/aspnetcore-10.0.md @@ -53,8 +53,6 @@ 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. diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md index b6e9eab3643c..1694a9a877b4 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md @@ -3,7 +3,7 @@ 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 provided to document, operation, and schema transformers includes a new `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. From 96c0d5c12b67dd69d98fd8a2db8f924a7d995791 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Fri, 9 May 2025 17:54:45 -0700 Subject: [PATCH 3/6] Fixed .csproj --- .../samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj index 980036af6279..a41d78e83987 100644 --- a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj @@ -6,16 +6,13 @@ enable enable true - - --openapi-version OpenApi3_1 + + --openapi-version OpenApi3_0 - - - - - + + From ce1fedfe90b908eb60e21af982fa63b073270236 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 12 May 2025 11:28:43 -0700 Subject: [PATCH 4/6] Updated openapi-version to 3.1 --- .../samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj index a41d78e83987..2dc29d00dd43 100644 --- a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj @@ -6,8 +6,8 @@ enable enable true - - --openapi-version OpenApi3_0 + + --openapi-version OpenApi3_1 From b923bd7a524b72108d077badfc98598a280cb668 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 12 May 2025 11:36:42 -0700 Subject: [PATCH 5/6] Linked inlcude in WN topic --- aspnetcore/release-notes/aspnetcore-10.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index 2b821741f388..1f93d35fb443 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/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. From 79763ed1b5eb665b4acd0e3c40d80ab6017d278b Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 12 May 2025 14:06:09 -0700 Subject: [PATCH 6/6] Removed comment --- .../aspnetcore-10/includes/OpenApiSchemasInTransformers.md | 1 - 1 file changed, 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md index 1694a9a877b4..255a20e932bc 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md @@ -12,5 +12,4 @@ To support adding the schema to the OpenAPI document, a `Document` property has 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. - :::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_Generate_OpenApiSchemas_for_type" highlight="6-7":::