Update WithOpenApi docs and scrub description IDs (#55924)

Author: captainsafia

src/OpenApi/src/Extensions/OpenApiEndpointConventionBuilderExtensions.cs

@@ -24,6 +24,10 @@ public static class OpenApiEndpointConventionBuilderExtensions
     /// Adds an OpenAPI annotation to <see cref="Endpoint.Metadata" /> associated
     /// with the current endpoint.
     /// </summary>
+    /// <remarks>
+    /// This method does not integrate with built-in OpenAPI document generation support in ASP.NET Core
+    /// and is primarily intended for consumption along-side Swashbuckle.AspNetCore.
+    /// </remarks>
     /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
     /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
     [RequiresDynamicCode(TrimWarningMessage)]
@@ -38,6 +42,10 @@ public static TBuilder WithOpenApi<TBuilder>(this TBuilder builder) where TBuild
     /// Adds an OpenAPI annotation to <see cref="Endpoint.Metadata" /> associated
     /// with the current endpoint and modifies it with the given <paramref name="configureOperation"/>.
     /// </summary>
+    /// <remarks>
+    /// This method does not integrate with built-in OpenAPI document generation support in ASP.NET Core
+    /// and is primarily intended for consumption along-side Swashbuckle.AspNetCore.
+    /// </remarks>
     /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
     /// <param name="configureOperation">An <see cref="Func{T, TResult}"/> that returns a new OpenAPI annotation given a generated operation.</param>
     /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>

src/OpenApi/src/Services/OpenApiConstants.cs

@@ -1,6 +1,8 @@
 // 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;
+
 namespace Microsoft.AspNetCore.OpenApi;
 
 internal static class OpenApiConstants
@@ -10,4 +12,18 @@ internal static class OpenApiConstants
     internal const string DefaultOpenApiRoute = "/openapi/{documentName}.json";
     internal const string DescriptionId = "x-aspnetcore-id";
     internal const string DefaultOpenApiResponseKey = "default";
+    // Since there's a finite set of operation types that can be included in a given
+    // OpenApiPaths, we can pre-allocate an array of these types and use a direct
+    // lookup on the OpenApiPaths dictionary to avoid allocating an enumerator
+    // over the KeyValuePairs in OpenApiPaths.
+    internal static readonly OperationType[] OperationTypes = [
+        OperationType.Get,
+        OperationType.Post,
+        OperationType.Put,
+        OperationType.Delete,
+        OperationType.Options,
+        OperationType.Head,
+        OperationType.Patch,
+        OperationType.Trace
+    ];
 }

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -31,6 +31,7 @@ internal sealed class OpenApiDocumentService(
 {
     private readonly OpenApiOptions _options = optionsMonitor.Get(documentName);
     private readonly OpenApiComponentService _componentService = serviceProvider.GetRequiredKeyedService<OpenApiComponentService>(documentName);
+    private readonly IOpenApiDocumentTransformer _scrubExtensionsTransformer = new ScrubExtensionsTransformer();
 
     private static readonly OpenApiEncoding _defaultFormEncoding = new OpenApiEncoding { Style = ParameterStyle.Form, Explode = true };
 
@@ -75,6 +76,8 @@ private async Task ApplyTransformersAsync(OpenApiDocument document, Cancellation
             var transformer = _options.DocumentTransformers[i];
             await transformer.TransformAsync(document, documentTransformerContext, cancellationToken);
         }
+        // Remove `x-aspnetcore-id` extension from operations after all transformers have run.
+        await _scrubExtensionsTransformer.TransformAsync(document, documentTransformerContext, cancellationToken);
     }
 
     // Note: Internal for testing.

src/OpenApi/src/Transformers/DelegateOpenApiDocumentTransformer.cs

@@ -9,20 +9,6 @@ namespace Microsoft.AspNetCore.OpenApi;
 
 internal sealed class DelegateOpenApiDocumentTransformer : IOpenApiDocumentTransformer
 {
-    // Since there's a finite set of operation types that can be included in a given
-    // OpenApiPaths, we can pre-allocate an array of these types and use a direct
-    // lookup on the OpenApiPaths dictionary to avoid allocating an enumerator
-    // over the KeyValuePairs in OpenApiPaths.
-    private static readonly OperationType[] _operationTypes = [
-        OperationType.Get,
-        OperationType.Post,
-        OperationType.Put,
-        OperationType.Delete,
-        OperationType.Options,
-        OperationType.Head,
-        OperationType.Patch,
-        OperationType.Trace
-    ];
     private readonly Func<OpenApiDocument, OpenApiDocumentTransformerContext, CancellationToken, Task>? _documentTransformer;
     private readonly Func<OpenApiOperation, OpenApiOperationTransformerContext, CancellationToken, Task>? _operationTransformer;
 
@@ -48,9 +34,9 @@ public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransf
             var documentService = context.ApplicationServices.GetRequiredKeyedService<OpenApiDocumentService>(context.DocumentName);
             foreach (var pathItem in document.Paths.Values)
             {
-                for (var i = 0; i < _operationTypes.Length; i++)
+                for (var i = 0; i < OpenApiConstants.OperationTypes.Length; i++)
                 {
-                    var operationType = _operationTypes[i];
+                    var operationType = OpenApiConstants.OperationTypes[i];
                     if (!pathItem.Operations.TryGetValue(operationType, out var operation))
                     {
                         continue;

src/OpenApi/src/Transformers/Implementations/ScrubExtensionsTransformer.cs

@@ -0,0 +1,31 @@
+// 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;
+
+namespace Microsoft.AspNetCore.OpenApi;
+
+/// <summary>
+/// A transformer class that removes implementation-specific extension properties
+/// from the OpenAPI document.
+/// </summary>
+internal sealed class ScrubExtensionsTransformer : IOpenApiDocumentTransformer
+{
+    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        foreach (var pathItem in document.Paths.Values)
+        {
+            for (var i = 0; i < OpenApiConstants.OperationTypes.Length; i++)
+            {
+                var operationType = OpenApiConstants.OperationTypes[i];
+                if (!pathItem.Operations.TryGetValue(operationType, out var operation))
+                {
+                    continue;
+                }
+
+                operation.Extensions.Remove(OpenApiConstants.DescriptionId);
+            }
+        }
+        return Task.CompletedTask;
+    }
+}

src/OpenApi/test/Integration/OpenApiDocumentIntegrationTests.cs

@@ -24,7 +24,6 @@ await Verifier.Verify(GetOpenApiJson(document))
             .UseDirectory(SkipOnHelixAttribute.OnHelix()
                 ? Path.Combine(Environment.GetEnvironmentVariable("HELIX_WORKITEM_ROOT"), "Integration", "snapshots")
                 : "snapshots")
-            .ScrubLinesContaining(Microsoft.AspNetCore.OpenApi.OpenApiConstants.DescriptionId)
             .UseParameters(documentName);
     }
 

src/OpenApi/test/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=forms.verified.txt

@@ -36,7 +36,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/forms/form-files": {
@@ -73,7 +73,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/forms/form-file-multiple": {
@@ -124,7 +124,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/forms/form-todo": {
@@ -207,7 +207,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/forms/forms-pocos-and-files": {
@@ -271,7 +271,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/getbyidandname/{id}/{name}": {
@@ -320,7 +320,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/forms": {
@@ -360,7 +360,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     }
   },

src/OpenApi/test/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=responses.verified.txt

@@ -70,7 +70,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/responses/200-only-xml": {
@@ -111,7 +111,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/responses/triangle": {
@@ -130,7 +130,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/responses/shape": {
@@ -172,7 +172,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/getbyidandname/{id}/{name}": {
@@ -221,7 +221,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/forms": {
@@ -261,7 +261,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     }
   },

src/OpenApi/test/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=v1.verified.txt

@@ -47,7 +47,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/v1/todos": {
@@ -102,7 +102,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/v1/todos/{id}": {
@@ -168,7 +168,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/getbyidandname/{id}/{name}": {
@@ -225,7 +225,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/forms": {
@@ -275,7 +275,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     }
   },

src/OpenApi/test/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=v2.verified.txt

@@ -31,7 +31,7 @@
               }
             }
           }
-        },
+        }
       },
       "post": {
         "tags": [
@@ -41,7 +41,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     },
     "/getbyidandname/{id}/{name}": {
@@ -90,7 +90,7 @@
               }
             }
           }
-        },
+        }
       }
     },
     "/forms": {
@@ -130,7 +130,7 @@
           "200": {
             "description": "OK"
           }
-        },
+        }
       }
     }
   },