Add APIs for OpenAPI document transformers

AspNetCore.sln

@@ -1790,6 +1790,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Components.WasmRemoteAuthen
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sample", "src\OpenApi\sample\Sample.csproj", "{6DEC24A8-A166-432F-8E3B-58FFCDA92F52}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNetCore.OpenApi.Microbenchmarks", "src\OpenApi\perf\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj", "{CF082AD5-E513-4A27-A6C7-3767E04D6205}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -10807,6 +10809,22 @@ Global
 		{6DEC24A8-A166-432F-8E3B-58FFCDA92F52}.Release|x64.Build.0 = Release|Any CPU
 		{6DEC24A8-A166-432F-8E3B-58FFCDA92F52}.Release|x86.ActiveCfg = Release|Any CPU
 		{6DEC24A8-A166-432F-8E3B-58FFCDA92F52}.Release|x86.Build.0 = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|arm64.ActiveCfg = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|arm64.Build.0 = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|x64.Build.0 = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Debug|x86.Build.0 = Debug|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|Any CPU.Build.0 = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|arm64.ActiveCfg = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|arm64.Build.0 = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|x64.ActiveCfg = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|x64.Build.0 = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|x86.ActiveCfg = Release|Any CPU
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -11691,6 +11709,7 @@ Global
 		{433F91E4-E39D-4EB0-B798-2998B3969A2C} = {6126DCE4-9692-4EE2-B240-C65743572995}
 		{8A021D6D-7935-4AB3-BB47-38D4FF9B0D13} = {6126DCE4-9692-4EE2-B240-C65743572995}
 		{6DEC24A8-A166-432F-8E3B-58FFCDA92F52} = {2299CCD8-8F9C-4F2B-A633-9BF4DA81022B}
+		{CF082AD5-E513-4A27-A6C7-3767E04D6205} = {2299CCD8-8F9C-4F2B-A633-9BF4DA81022B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {3E8720B3-DBDD-498C-B383-2CC32A054E8F}

eng/Versions.props

@@ -290,7 +290,7 @@
     <!-- 3rd party dependencies -->
     <AzureIdentityVersion>1.10.3</AzureIdentityVersion>
     <AngleSharpVersion>0.9.9</AngleSharpVersion>
-    <BenchmarkDotNetVersion>0.13.0</BenchmarkDotNetVersion>
+    <BenchmarkDotNetVersion>0.13.12</BenchmarkDotNetVersion>
     <CastleCoreVersion>4.2.1</CastleCoreVersion>
     <CommandLineParserVersion>2.3.0</CommandLineParserVersion>
     <FSharpCoreVersion>6.0.0</FSharpCoreVersion>

src/OpenApi/OpenApi.slnf

@@ -9,7 +9,8 @@
       "src\\Http\\Routing\\src\\Microsoft.AspNetCore.Routing.csproj",
       "src\\OpenApi\\src\\Microsoft.AspNetCore.OpenApi.csproj",
       "src\\OpenApi\\test\\Microsoft.AspNetCore.OpenApi.Tests.csproj",
-      "src\\OpenApi\\sample\\Sample.csproj"
+      "src\\OpenApi\\sample\\Sample.csproj",
+      "src\\OpenApi\\perf\\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj"
     ]
   }
 }

src/OpenApi/perf/AssemblyInfo.cs

@@ -0,0 +1,4 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+[assembly: BenchmarkDotNet.Attributes.AspNetCoreBenchmark]

src/OpenApi/perf/Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
+    <OutputType>Exe</OutputType>
+    <PreserveCompilationContext>true</PreserveCompilationContext>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Reference Include="BenchmarkDotNet" />
+    <Reference Include="Microsoft.AspNetCore" />
+    <Reference Include="Microsoft.AspNetCore.OpenApi" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\test\Microsoft.AspNetCore.OpenApi.Tests.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Compile Include="$(SharedSourceRoot)BenchmarkRunner\*.cs" />
+  </ItemGroup>
+
+</Project>

src/OpenApi/perf/TransformersBenchmark.cs

@@ -0,0 +1,106 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Reflection.Metadata;
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Diagnosers;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.OpenApi.Models;
+
+namespace Microsoft.AspNetCore.OpenApi.Microbenchmarks;
+
+/// <summary>
+/// The following benchmarks are used to assess the memory and performance
+/// impact of different types of transformers. In particular, we want to
+/// measure the impact of (a) context-object creation and caching and (b)
+/// enumerator usage when processing operations in a given document.
+/// </summary>
+[MemoryDiagnoser]
+[EventPipeProfiler(EventPipeProfile.GcVerbose)]
+public class TransformersBenchmark : OpenApiDocumentServiceTestBase
+{
+    [Params(10, 100, 1000)]
+    public int InvocationCount { get; set; }
+
+    private readonly IEndpointRouteBuilder _builder = CreateBuilder();
+    private readonly OpenApiOptions _options = new OpenApiOptions();
+    private OpenApiDocumentService _documentService;
+
+    [GlobalSetup(Target = nameof(OperationTransformerAsDelegate))]
+    public void OperationTransformerAsDelegate_Setup()
+    {
+        _builder.MapGet("/", () => { });
+        for (var i = 0; i <= 1000; i++)
+        {
+            _options.UseOperationTransformer((operation, context, token) =>
+            {
+                operation.Description = "New Description";
+                return Task.CompletedTask;
+            });
+        }
+        _documentService = CreateDocumentService(_builder, _options);
+    }
+
+    [GlobalSetup(Target = nameof(ActivatedDocumentTransformer))]
+    public void ActivatedDocumentTransformer_Setup()
+    {
+        _builder.MapGet("/", () => { });
+        for (var i = 0; i <= 1000; i++)
+        {
+            _options.UseTransformer<ActivatedTransformer>();
+        }
+        _documentService = CreateDocumentService(_builder, _options);
+    }
+
+    [GlobalSetup(Target = nameof(DocumentTransformerAsDelegate))]
+    public void DocumentTransformerAsDelegate_Delegate()
+    {
+        _builder.MapGet("/", () => { });
+        for (var i = 0; i <= 1000; i++)
+        {
+            _options.UseTransformer((document, context, token) =>
+            {
+                document.Info.Description = "New Description";
+                return Task.CompletedTask;
+            });
+        }
+        _documentService = CreateDocumentService(_builder, _options);
+    }
+
+    [Benchmark]
+    public async Task OperationTransformerAsDelegate()
+    {
+        for (var i = 0; i < InvocationCount; i++)
+        {
+            await _documentService.GetOpenApiDocumentAsync();
+        }
+    }
+
+    [Benchmark]
+    public async Task ActivatedDocumentTransformer()
+    {
+        for (var i = 0; i < InvocationCount; i++)
+        {
+            await _documentService.GetOpenApiDocumentAsync();
+        }
+    }
+
+    [Benchmark]
+    public async Task DocumentTransformerAsDelegate()
+    {
+        for (var i = 0; i < InvocationCount; i++)
+        {
+            await _documentService.GetOpenApiDocumentAsync();
+        }
+    }
+
+    private class ActivatedTransformer : IOpenApiDocumentTransformer
+    {
+        public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+        {
+            document.Info.Description = "Info Description";
+            return Task.CompletedTask;
+        }
+    }
+}

src/OpenApi/sample/Program.cs

@@ -1,10 +1,24 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using Microsoft.OpenApi.Models;
+
 var builder = WebApplication.CreateBuilder(args);
 
-builder.Services.AddOpenApi("v1");
-builder.Services.AddOpenApi("v2");
+builder.Services.AddAuthentication().AddJwtBearer();
+
+builder.Services.AddOpenApi("v1", options =>
+{
+    options.AddHeader("X-Version", "1.0");
+    options.UseTransformer<BearerSecuritySchemeTransformer>();
+});
+builder.Services.AddOpenApi("v2", options => {
+    options.UseTransformer(new AddContactTransformer());
+    options.UseTransformer((document, context, token) => {
+        document.Info.License = new OpenApiLicense { Name = "MIT" };
+        return Task.CompletedTask;
+    });
+});
 
 var app = builder.Build();
 

src/OpenApi/sample/Sample.csproj

@@ -8,6 +8,7 @@
 
   <ItemGroup>
     <Reference Include="Microsoft.AspNetCore" />
+    <Reference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
     <Reference Include="Microsoft.AspNetCore.Hosting" />
     <Reference Include="Microsoft.AspNetCore.OpenApi" />
     <Reference Include="Microsoft.AspNetCore.Http" />

src/OpenApi/sample/Transformers/AddBearerSecuritySchemeTransformer.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+
+public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var authenticationSchemes = (authenticationSchemeProvider is not null)
+                ? await authenticationSchemeProvider.GetAllSchemesAsync()
+                : [];
+        var requirements = authenticationSchemes
+                .Where(authScheme => authScheme.Name == "Bearer")
+                .ToDictionary(
+                    (authScheme) => authScheme.Name,
+                    (authScheme) => new OpenApiSecurityScheme
+                    {
+                        Type = SecuritySchemeType.Http,
+                        Scheme = "bearer", // "bearer" refers to the header name here
+                        In = ParameterLocation.Header,
+                        BearerFormat = "Json Web Token"
+                    });
+        document.Components ??= new OpenApiComponents();
+        document.Components.SecuritySchemes = requirements;
+    }
+}

src/OpenApi/sample/Transformers/AddContactTransformer.cs

@@ -0,0 +1,18 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+
+public sealed class AddContactTransformer : IOpenApiDocumentTransformer
+{
+    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        document.Info.Contact = new OpenApiContact
+        {
+            Name = "OpenAPI Enthusiast",
+            Email = "[email protected]"
+        };
+        return Task.CompletedTask;
+    }
+}

src/OpenApi/sample/Transformers/OperationTransformers.cs

@@ -0,0 +1,26 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Extensions;
+
+public static class OperationTransformers
+{
+    public static OpenApiOptions AddHeader(this OpenApiOptions options, string headerName, string defaultValue)
+    {
+        return options.UseOperationTransformer((operation, context, cancellationToken) =>
+        {
+            var schema = OpenApiTypeMapper.MapTypeToOpenApiPrimitiveType(typeof(string));
+            schema.Default = new OpenApiString(defaultValue);
+            operation.Parameters.Add(new OpenApiParameter
+            {
+                Name = headerName,
+                In = ParameterLocation.Header,
+                Schema = schema
+            });
+            return Task.CompletedTask;
+        });
+    }
+}

src/OpenApi/src/Extensions/OpenApiEndpointRouteBuilderExtensions.cs

@@ -43,7 +43,7 @@ public static IEndpointConventionBuilder MapOpenApi(this IEndpointRouteBuilder e
                 }
                 else
                 {
-                    var document = await documentService.GetOpenApiDocumentAsync();
+                    var document = await documentService.GetOpenApiDocumentAsync(context.RequestAborted);
                     var documentOptions = options.Get(documentName);
                     using var output = MemoryBufferWriter.Get();
                     using var writer = Utf8BufferTextWriter.Get(output);

src/OpenApi/src/Microsoft.AspNetCore.OpenApi.csproj

@@ -27,6 +27,7 @@
 
   <ItemGroup>
     <InternalsVisibleTo Include="Microsoft.AspNetCore.OpenApi.Tests" />
+    <InternalsVisibleTo Include="Microsoft.AspNetCore.OpenApi.Microbenchmarks" />
   </ItemGroup>
 
   <ItemGroup>

src/OpenApi/src/PublicAPI.Unshipped.txt

@@ -1,15 +1,37 @@
 #nullable enable
 Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions
+Microsoft.AspNetCore.OpenApi.IOpenApiDocumentTransformer.TransformAsync(Microsoft.OpenApi.Models.OpenApiDocument! document, Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext! context, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.Task!
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.Description.get -> Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription!
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.Description.init -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.DocumentName.get -> string!
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiOptions() -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersion.get -> Microsoft.OpenApi.OpenApiSpecVersion
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersion.set -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.ShouldInclude.get -> System.Func<Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription!, bool>!
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.ShouldInclude.set -> void
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.UseOperationTransformer(System.Func<Microsoft.OpenApi.Models.OpenApiOperation!, Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext!, System.Threading.CancellationToken, System.Threading.Tasks.Task!>! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.UseTransformer(Microsoft.AspNetCore.OpenApi.IOpenApiDocumentTransformer! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.UseTransformer(System.Func<Microsoft.OpenApi.Models.OpenApiDocument!, Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext!, System.Threading.CancellationToken, System.Threading.Tasks.Task!>! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.UseTransformer<TTransformerType>() -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
 Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions
 static Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions.MapOpenApi(this Microsoft.AspNetCore.Routing.IEndpointRouteBuilder! endpoints, string! pattern = "/openapi/{documentName}.json") -> Microsoft.AspNetCore.Builder.IEndpointConventionBuilder!
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, string! documentName) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, string! documentName, System.Action<Microsoft.AspNetCore.OpenApi.OpenApiOptions!>! configureOptions) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<Microsoft.AspNetCore.OpenApi.OpenApiOptions!>! configureOptions) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
+Microsoft.AspNetCore.OpenApi.IOpenApiDocumentTransformer
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.ApplicationServices.get -> System.IServiceProvider!
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.ApplicationServices.init -> void
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.DescriptionGroups.get -> System.Collections.Generic.IReadOnlyList<Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescriptionGroup!>!
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.DescriptionGroups.init -> void
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.DocumentName.get -> string!
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.DocumentName.init -> void
+Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.OpenApiDocumentTransformerContext() -> void
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.ApplicationServices.get -> System.IServiceProvider!
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.ApplicationServices.init -> void
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.DocumentName.get -> string!
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.DocumentName.init -> void
+Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.OpenApiOperationTransformerContext() -> void

src/OpenApi/src/Services/OpenApiConstants.cs

@@ -8,4 +8,5 @@ internal static class OpenApiConstants
     internal const string DefaultDocumentName = "v1";
     internal const string DefaultOpenApiVersion = "1.0.0";
     internal const string DefaultOpenApiRoute = "/openapi/{documentName}.json";
+    internal const string DescriptionId = "x-aspnetcore-id";
 }