Fix description of transformer execution order (#35205)

* Fix description of transformer execution order

Co-authored-by: Rick Anderson <[email protected]>

Author: mikekistler

Diff for: aspnetcore/fundamentals/openapi/customize-openapi.md

@@ -42,9 +42,23 @@ Transformers can be registered onto the document by calling the <xref:Microsoft.
 
 ### Execution order for transformers
 
-Transformers execute in first-in first-out order based on registration. In the following snippet, the document transformer has access to the modifications made by the operation transformer:
-
-[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_transInOut&highlight=3-9)]
+Transformers are executed as follows:
+
+* Schema transformers are executed when a schema is registered to the document. Schema transformers are executed in the order in which they were added.
+All schemas are added to the document before any operation processing occurs, so all schema transformers are executed before any operation transformers.
+* Operation transformers are executed when an operation is added to the document. Operation transformers are executed in the order in which they were added.
+All operations are added to the document before any document transformers are executed.
+* Document transformers are executed when the document is generated. This is the final pass over the document, and all operations and schemas have been add by this point.
+* When an app is configured to generate multiple OpenAPI documents, transformers are executed for each document independently.
+
+For example, in the following snippet:
+* `SchemaTransformer2` is executed and has access to the modifications made by `SchemaTransformer1`.
+* Both `OperationTransformer1` and `OperationTransformer2` have access to the modifications made by both schema transformers for the types involved in the operation they are called to process.
+* `OperationTransformer2` is executed after `OperationTransformer1`, so it has access to the modifications made by `OperationTransformer1`.
+* Both `DocumentTransformer1` and `DocumentTransformer2` are executed after all operations and schemas have been added to the document, so they have access to all modifications made by the operation and schema transformers.
+* `DocumentTransformer2` is executed after `DocumentTransformer1`, so it has access to the modifications made by `DocumentTransformer1`.
+
+[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_transInOut&highlight=6-14)]
 
 ## Use document transformers
 

Diff for: aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs

@@ -1,8 +1,8 @@
 //#define DEFAULT
-//#define DOCUMENTtransformerInOut
+#define DOCUMENTtransformerInOut
 //#define DOCUMENTtransformer1
 //#define DOCUMENTtransformer2
-#define DOCUMENTtransformerUse999
+// #define DOCUMENTtransformerUse999
 //#define FIRST
 //#define OPENAPIWITHSCALAR
 //#define MAPOPENAPIWITHCACHING
@@ -296,7 +296,7 @@ public class Body {
 if (app.Environment.IsDevelopment())
 {
     app.MapOpenApi();
-    
+
     app.UseSwaggerUI(options =>
     {
         options.SwaggerEndpoint("/openapi/v1.json", "v1");
@@ -484,14 +484,19 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext
 
 #if DOCUMENTtransformerInOut
 // <snippet_transInOut>
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+
 var builder = WebApplication.CreateBuilder();
 
 builder.Services.AddOpenApi(options =>
 {
-    options.AddOperationTransformer((operation, context, cancellationToken)
-                                     => Task.CompletedTask);
-    options.AddDocumentTransformer((document, context, cancellationToken)
-                                     => Task.CompletedTask);
+    options.AddDocumentTransformer<DocumentTransformer1>();
+    options.AddSchemaTransformer<SchemaTransformer1>();
+    options.AddDocumentTransformer<DocumentTransformer2>();
+    options.AddOperationTransformer<OperationTransformer1>();
+    options.AddSchemaTransformer<SchemaTransformer2>();
+    options.AddOperationTransformer<OperationTransformer2>();
 });
 
 var app = builder.Build();
@@ -506,4 +511,34 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext
 app.Run();
 // </snippet_transInOut>
 
+internal class DocumentTransformer1 : IOpenApiDocumentTransformer
+{
+    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken) => Task.CompletedTask;
+}
+
+internal class DocumentTransformer2 : IOpenApiDocumentTransformer
+{
+    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken) => Task.CompletedTask;
+}
+
+internal class OperationTransformer1 : IOpenApiOperationTransformer
+{
+    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken) => Task.CompletedTask;
+}
+
+internal class OperationTransformer2 : IOpenApiOperationTransformer
+{
+    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken) => Task.CompletedTask;
+}
+
+internal class SchemaTransformer1 : IOpenApiSchemaTransformer
+{
+    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken) => Task.CompletedTask;
+}
+
+internal class SchemaTransformer2 : IOpenApiSchemaTransformer
+{
+    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken) => Task.CompletedTask;
+}
+
 #endif