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..255a20e932bc 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md @@ -1,42 +1,15 @@ ### 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 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. - -```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..2dc29d00dd43 100644 --- a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj @@ -6,13 +6,13 @@ enable enable true - - --openapi-version OpenApi3_0 + + --openapi-version OpenApi3_1 - +