Add OpenAPI operation and schema transformer interfaces (#56395)

* Add operation and schema transformer interfaces

- Add `IOpenApiOperationTransformer`.
- Add `IOpenApiSchemaTransformer`.
- Rename `Use*Transfomer()` methods to `Add*Transformer()`.

Resolves #56022.

* Add operation and schema transform examples

Add examples for DI-activated operation and schema transformers.

* Fix rebase

Fix mistake during rebase.

* Run operation transforms before documents

Run operation transformers before any document transformers.

* Move transformer

Add type-based transformer for operations to its own class.

* Revert submodule

Revert accidental change to submodule during rebase.

* Apply review feedback

- Remove collection expression.
- Fix two typos.
- Add parameter to benchmark.

Author: martincostello

AspNetCore.sln

@@ -1788,7 +1788,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NotReferencedInWasmCodePack
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Components.WasmRemoteAuthentication", "src\Components\test\testassets\Components.WasmRemoteAuthentication\Components.WasmRemoteAuthentication.csproj", "{8A021D6D-7935-4AB3-BB47-38D4FF9B0D13}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sample", "src\OpenApi\sample\Sample.csproj", "{6DEC24A8-A166-432F-8E3B-58FFCDA92F52}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Sample", "src\OpenApi\sample\Sample.csproj", "{6DEC24A8-A166-432F-8E3B-58FFCDA92F52}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Hybrid", "Hybrid", "{2D64CA23-6E81-488E-A7D3-9BDF87240098}"
 EndProject
@@ -1802,7 +1802,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Extensions.Cachin
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "perf", "perf", "{9DC6B242-457B-4767-A84B-C3D23B76C642}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNetCore.OpenApi.Microbenchmarks", "src\OpenApi\perf\Microbenchmarks\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj", "{D53F0EF7-0CDC-49B4-AA2D-229901B0A734}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.AspNetCore.OpenApi.Microbenchmarks", "src\OpenApi\perf\Microbenchmarks\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj", "{D53F0EF7-0CDC-49B4-AA2D-229901B0A734}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KeyManagementSimulator", "src\DataProtection\samples\KeyManagementSimulator\KeyManagementSimulator.csproj", "{5B5F86CC-3598-463C-9F9B-F78FBB6642F4}"
 EndProject

src/OpenApi/OpenApi.slnf

@@ -2,15 +2,19 @@
   "solution": {
     "path": "..\\..\\AspNetCore.sln",
     "projects": [
+      "src\\Extensions\\Features\\src\\Microsoft.Extensions.Features.csproj",
       "src\\Hosting\\Abstractions\\src\\Microsoft.AspNetCore.Hosting.Abstractions.csproj",
       "src\\Hosting\\Hosting\\src\\Microsoft.AspNetCore.Hosting.csproj",
+      "src\\Http\\Headers\\src\\Microsoft.Net.Http.Headers.csproj",
       "src\\Http\\Http.Abstractions\\src\\Microsoft.AspNetCore.Http.Abstractions.csproj",
       "src\\Http\\Http\\src\\Microsoft.AspNetCore.Http.csproj",
+      "src\\Http\\Http.Features\\src\\Microsoft.AspNetCore.Http.Features.csproj",
       "src\\Http\\Routing\\src\\Microsoft.AspNetCore.Routing.csproj",
+      "src\\OpenApi\\perf\\Microbenchmarks\\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj",
+      "src\\OpenApi\\sample\\Sample.csproj",
       "src\\OpenApi\\src\\Microsoft.AspNetCore.OpenApi.csproj",
       "src\\OpenApi\\test\\Microsoft.AspNetCore.OpenApi.Tests.csproj",
-      "src\\OpenApi\\sample\\Sample.csproj",
-      "src\\OpenApi\\perf\\Microbenchmarks\\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj"
+      "src\\Servers\\Connections.Abstractions\\src\\Microsoft.AspNetCore.Connections.Abstractions.csproj"
     ]
   }
 }

src/OpenApi/perf/Microbenchmarks/TransformersBenchmark.cs

@@ -21,16 +21,27 @@ public class TransformersBenchmark : OpenApiDocumentServiceTestBase
     public int TransformerCount { get; set; }
 
     private readonly IEndpointRouteBuilder _builder = CreateBuilder();
-    private readonly OpenApiOptions _options = new OpenApiOptions();
+    private readonly OpenApiOptions _options = new();
     private OpenApiDocumentService _documentService;
 
+    [GlobalSetup(Target = nameof(ActivatedOperationTransformer))]
+    public void ActivatedOperationTransformer_Setup()
+    {
+        _builder.MapGet("/", () => { });
+        for (var i = 0; i <= TransformerCount; i++)
+        {
+            _options.AddOperationTransformer<OperationTransformer>();
+        }
+        _documentService = CreateDocumentService(_builder, _options);
+    }
+
     [GlobalSetup(Target = nameof(OperationTransformerAsDelegate))]
     public void OperationTransformerAsDelegate_Setup()
     {
         _builder.MapGet("/", () => { });
         for (var i = 0; i <= TransformerCount; i++)
         {
-            _options.UseOperationTransformer((operation, context, token) =>
+            _options.AddOperationTransformer((operation, context, token) =>
             {
                 operation.Description = "New Description";
                 return Task.CompletedTask;
@@ -45,7 +56,7 @@ public void ActivatedDocumentTransformer_Setup()
         _builder.MapGet("/", () => { });
         for (var i = 0; i <= TransformerCount; i++)
         {
-            _options.UseTransformer<ActivatedTransformer>();
+            _options.AddDocumentTransformer<DocumentTransformer>();
         }
         _documentService = CreateDocumentService(_builder, _options);
     }
@@ -56,7 +67,7 @@ public void DocumentTransformerAsDelegate_Delegate()
         _builder.MapGet("/", () => { });
         for (var i = 0; i <= TransformerCount; i++)
         {
-            _options.UseTransformer((document, context, token) =>
+            _options.AddDocumentTransformer((document, context, token) =>
             {
                 document.Info.Description = "New Description";
                 return Task.CompletedTask;
@@ -65,13 +76,24 @@ public void DocumentTransformerAsDelegate_Delegate()
         _documentService = CreateDocumentService(_builder, _options);
     }
 
-    [GlobalSetup(Target = nameof(SchemaTransformer))]
+    [GlobalSetup(Target = nameof(ActivatedSchemaTransformer))]
+    public void ActivatedSchemaTransformer_Setup()
+    {
+        _builder.MapPost("/", (Todo todo) => todo);
+        for (var i = 0; i <= TransformerCount; i++)
+        {
+            _options.AddSchemaTransformer<SchemaTransformer>();
+        }
+        _documentService = CreateDocumentService(_builder, _options);
+    }
+
+    [GlobalSetup(Target = nameof(SchemaTransformerAsDelegate))]
     public void SchemaTransformer_Setup()
     {
         _builder.MapPost("/", (Todo todo) => todo);
         for (var i = 0; i <= TransformerCount; i++)
         {
-            _options.UseSchemaTransformer((schema, context, token) =>
+            _options.AddSchemaTransformer((schema, context, token) =>
             {
                 if (context.Type == typeof(Todo) && context.ParameterDescription != null)
                 {
@@ -87,6 +109,12 @@ public void SchemaTransformer_Setup()
         _documentService = CreateDocumentService(_builder, _options);
     }
 
+    [Benchmark]
+    public async Task ActivatedOperationTransformer()
+    {
+        await _documentService.GetOpenApiDocumentAsync();
+    }
+
     [Benchmark]
     public async Task OperationTransformerAsDelegate()
     {
@@ -106,17 +134,48 @@ public async Task DocumentTransformerAsDelegate()
     }
 
     [Benchmark]
-    public async Task SchemaTransformer()
+    public async Task ActivatedSchemaTransformer()
+    {
+        await _documentService.GetOpenApiDocumentAsync();
+    }
+
+    [Benchmark]
+    public async Task SchemaTransformerAsDelegate()
     {
         await _documentService.GetOpenApiDocumentAsync();
     }
 
-    private class ActivatedTransformer : IOpenApiDocumentTransformer
+    private class DocumentTransformer : IOpenApiDocumentTransformer
     {
         public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
         {
             document.Info.Description = "Info Description";
             return Task.CompletedTask;
         }
     }
+
+    private class OperationTransformer : IOpenApiOperationTransformer
+    {
+        public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
+        {
+            operation.Description = "Operation Description";
+            return Task.CompletedTask;
+        }
+    }
+
+    private class SchemaTransformer : IOpenApiSchemaTransformer
+    {
+        public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
+        {
+            if (context.Type == typeof(Todo) && context.ParameterDescription != null)
+            {
+                schema.Extensions["x-my-extension"] = new OpenApiString(context.ParameterDescription.Name);
+            }
+            else
+            {
+                schema.Extensions["x-my-extension"] = new OpenApiString("response");
+            }
+            return Task.CompletedTask;
+        }
+    }
 }

src/OpenApi/sample/Program.cs

@@ -1,7 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-using System.Collections.Frozen;
 using System.Collections.Immutable;
 using System.ComponentModel;
 using Microsoft.AspNetCore.Http.HttpResults;
@@ -19,11 +18,13 @@
 builder.Services.AddOpenApi("v1", options =>
 {
     options.AddHeader("X-Version", "1.0");
-    options.UseTransformer<BearerSecuritySchemeTransformer>();
+    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
 });
 builder.Services.AddOpenApi("v2", options => {
-    options.UseTransformer(new AddContactTransformer());
-    options.UseTransformer((document, context, token) => {
+    options.AddSchemaTransformer<AddExternalDocsTransformer>();
+    options.AddOperationTransformer<AddExternalDocsTransformer>();
+    options.AddDocumentTransformer(new AddContactTransformer());
+    options.AddDocumentTransformer((document, context, token) => {
         document.Info.License = new OpenApiLicense { Name = "MIT" };
         return Task.CompletedTask;
     });
@@ -82,7 +83,8 @@
 v2.MapGet("/users", () => new [] { "alice", "bob" })
     .WithTags("users");
 
-v2.MapPost("/users", () => Results.Created("/users/1", new { Id = 1, Name = "Test user" }));
+v2.MapPost("/users", () => Results.Created("/users/1", new { Id = 1, Name = "Test user" }))
+  .WithName("CreateUser");
 
 responses.MapGet("/200-add-xml", () => new TodoWithDueDate(1, "Test todo", false, DateTime.Now.AddDays(1), DateTime.Now))
     .Produces<Todo>(additionalContentTypes: "text/xml");

src/OpenApi/sample/Transformers/AddExternalDocsTransformer.cs

@@ -0,0 +1,42 @@
+// 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;
+
+namespace Sample.Transformers;
+
+public sealed class AddExternalDocsTransformer(IConfiguration configuration) : IOpenApiOperationTransformer, IOpenApiSchemaTransformer
+{
+    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
+    {
+        if (operation.OperationId is { Length: > 0 } id &&
+            Uri.TryCreate(configuration["DocumentationBaseUrl"], UriKind.Absolute, out var baseUri))
+        {
+            var url = new Uri(baseUri, $"/api/docs/operations/{Uri.EscapeDataString(id)}");
+
+            operation.ExternalDocs = new OpenApiExternalDocs
+            {
+                Description = "Documentation for this OpenAPI endpoint",
+                Url = url
+            };
+        }
+
+        return Task.CompletedTask;
+    }
+
+    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
+    {
+        if (Uri.TryCreate(configuration["DocumentationBaseUrl"], UriKind.Absolute, out var baseUri))
+        {
+            var url = new Uri(baseUri, $"/api/docs/schemas/{Uri.EscapeDataString(schema.Type)}");
+
+            schema.ExternalDocs = new OpenApiExternalDocs
+            {
+                Description = "Documentation for this OpenAPI schema",
+                Url = url
+            };
+        }
+        return Task.CompletedTask;
+    }
+}

src/OpenApi/sample/Transformers/OperationTransformers.cs

@@ -2,17 +2,17 @@
 // 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;
+using Microsoft.OpenApi.Models;
 
 namespace Sample.Transformers;
 
 public static class OperationTransformers
 {
     public static OpenApiOptions AddHeader(this OpenApiOptions options, string headerName, string defaultValue)
     {
-        return options.UseOperationTransformer((operation, context, cancellationToken) =>
+        return options.AddOperationTransformer((operation, context, cancellationToken) =>
         {
             var schema = OpenApiTypeMapper.MapTypeToOpenApiPrimitiveType(typeof(string));
             schema.Default = new OpenApiString(defaultValue);

src/OpenApi/sample/appsettings.json

@@ -1,4 +1,5 @@
 {
+  "DocumentationBaseUrl": "https://example.com",
   "Logging": {
     "LogLevel": {
       "Default": "Information",

src/OpenApi/src/PublicAPI.Unshipped.txt

@@ -1,9 +1,17 @@
 #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.IOpenApiOperationTransformer
+Microsoft.AspNetCore.OpenApi.IOpenApiOperationTransformer.TransformAsync(Microsoft.OpenApi.Models.OpenApiOperation! operation, Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext! context, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.Task!
+Microsoft.AspNetCore.OpenApi.IOpenApiSchemaTransformer
+Microsoft.AspNetCore.OpenApi.IOpenApiSchemaTransformer.TransformAsync(Microsoft.OpenApi.Models.OpenApiSchema! schema, Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext! 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.AddOperationTransformer(Microsoft.AspNetCore.OpenApi.IOpenApiOperationTransformer! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.AddOperationTransformer<TTransformerType>() -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.AddSchemaTransformer(Microsoft.AspNetCore.OpenApi.IOpenApiSchemaTransformer! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.AddSchemaTransformer<TTransformerType>() -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.CreateSchemaReferenceId.get -> System.Func<System.Text.Json.Serialization.Metadata.JsonTypeInfo!, string?>!
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.CreateSchemaReferenceId.set -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.DocumentName.get -> string!
@@ -12,11 +20,11 @@ Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersion.get -> Microsoft.Open
 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.UseSchemaTransformer(System.Func<Microsoft.OpenApi.Models.OpenApiSchema!, Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext!, 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.AspNetCore.OpenApi.OpenApiOptions.AddOperationTransformer(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.AddSchemaTransformer(System.Func<Microsoft.OpenApi.Models.OpenApiSchema!, Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext!, System.Threading.CancellationToken, System.Threading.Tasks.Task!>! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.AddDocumentTransformer(Microsoft.AspNetCore.OpenApi.IOpenApiDocumentTransformer! transformer) -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.AddDocumentTransformer(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.AddDocumentTransformer<TTransformerType>() -> Microsoft.AspNetCore.OpenApi.OpenApiOptions!
 Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext
 Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext.ApplicationServices.get -> System.IServiceProvider!
 Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext.ApplicationServices.init -> void