Fix description of transformer execution order

Author: mikekistler

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 register 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 application is configured to generate multiple OpenAPI documents, each document is generated in the order in which it was registered, and the transformers are executed as documents are generated.
+
+For example, in the following snippet:
+* SchemaTransformer2 is executed 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
 

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