Add documentation about AddOpenApiOperationTransformer (#36207)

Author: sander1095

aspnetcore/fundamentals/openapi/customize-openapi.md

@@ -102,6 +102,14 @@ For example, the following operation transformer adds `500` as a response status
 
 [!code-csharp[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs?name=snippet_operationtransformer1)]
 
+<!-- UPDATE 10.0 - API doc cross-link:
+                   <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.AddOpenApiOperationTransformer%2A>
+-->
+ 
+Operation transformers can also be added to specific endpoint with the `AddOpenApiOperationTransformer` API, instead of all endpoints in a document. This can be useful to change specific OpenAPI data for a specific endpoint, like adding a security scheme, response description or other OpenAPI operation properties. The following example demonstrates adding an operation transformer to a deprecated endpoint specifically, which marks the endpoint as deprecated in the OpenAPI document.
+
+[!code-csharp[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs?name=snippet_operationtransformer2)]
+
 ## Use schema transformers
 
 Schemas are the data models that are used in request and response bodies in an OpenAPI document. Schema transformers are useful when a modification:

aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs

@@ -10,6 +10,7 @@
 //#define SWAGGERUI
 //#define MULTIDOC_OPERATIONtransformer1
 //#define OPERATIONtransformer1
+//#define OPERATIONtransformer2
 
 #if DEFAULT
 // <snippet_default>
@@ -178,6 +179,37 @@ public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransf
 // </snippet_operationtransformer1>
 #endif
 
+#if OPERATIONtransformer2
+// <snippet_operationtransformer2>
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi();
+}
+
+app.MapGet("/old", () => "This endpoint is old and should not be used anymore")
+.AddOpenApiOperationTransformer((operation, context, cancellationToken) =>
+{
+    operation.Deprecated = true;
+    return Task.CompletedTask;
+});
+
+app.MapGet("/new", () => "This endpoint replaces /old");
+
+app.Run();
+// </snippet_operationtransformer2>
+#endif
+
 #if MULTIDOC_OPERATIONtransformer1
 // <snippet_multidoc_operationtransformer1>
 using Microsoft.AspNetCore.Authentication;