Add support for SuppressApi to close #34068

Author: captainsafia

src/Http/Routing/src/ISuppressApiMetadata.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Microsoft.AspNetCore.Http;
+
+namespace Microsoft.AspNetCore.Routing
+{
+    /// <summary>
+    /// Specifies an endpoint name in <see cref="Endpoint.Metadata"/>.
+    /// </summary>
+    /// <remarks>
+    /// Endpoint names must be unique within an application, and can be used to unambiguously
+    /// identify a desired endpoint for URI generation using <see cref="LinkGenerator"/>.
+    /// </remarks>
+    public interface ISuppressApiMetadata
+    {
+        /// <summary>
+        /// Gets the endpoint name.
+        /// </summary>
+        bool SuppressApi { get; }
+    }
+}

src/Http/Routing/src/PublicAPI.Unshipped.txt

@@ -35,4 +35,9 @@ Microsoft.AspNetCore.Routing.EndpointNameAttribute
 Microsoft.AspNetCore.Routing.EndpointNameAttribute.EndpointNameAttribute(string! endpointName) -> void
 Microsoft.AspNetCore.Routing.EndpointNameAttribute.EndpointName.get -> string!
 static Microsoft.AspNetCore.Builder.RoutingEndpointConventionBuilderExtensions.WithName<TBuilder>(this TBuilder builder, string! endpointName) -> TBuilder
-static Microsoft.AspNetCore.Builder.RoutingEndpointConventionBuilderExtensions.WithGroupName<TBuilder>(this TBuilder builder, string! endpointGroupName) -> TBuilder
+static Microsoft.AspNetCore.Builder.RoutingEndpointConventionBuilderExtensions.WithGroupName<TBuilder>(this TBuilder builder, string! endpointGroupName) -> TBuilder
+Microsoft.AspNetCore.Routing.ISuppressApiMetadata
+Microsoft.AspNetCore.Routing.ISuppressApiMetadata.SuppressApi.get -> bool
+Microsoft.AspNetCore.Routing.SuppressApiMetadata
+Microsoft.AspNetCore.Routing.SuppressApiMetadata.SuppressApiMetadata() -> void
+Microsoft.AspNetCore.Routing.SuppressApiMetadata.SuppressApi.get -> bool

src/Http/Routing/src/SuppressApiMetadata.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Microsoft.AspNetCore.Http;
+
+namespace Microsoft.AspNetCore.Routing
+{
+    /// <summary>
+    /// Specifies an endpoint name in <see cref="Endpoint.Metadata"/>.
+    /// </summary>
+    /// <remarks>
+    /// Endpoint names must be unique within an application, and can be used to unambiguously
+    /// identify a desired endpoint for URI generation using <see cref="LinkGenerator"/>.
+    /// </remarks>
+    public sealed class SuppressApiMetadata : ISuppressApiMetadata
+    {
+        /// <summary>
+        /// Gets the endpoint name.
+        /// </summary>
+        public bool SuppressApi => true;
+    }
+}

src/Mvc/Mvc.ApiExplorer/src/EndpointMetadataApiDescriptionProvider.cs

@@ -52,7 +52,9 @@ public void OnProvidersExecuting(ApiDescriptionProviderContext context)
             {
                 if (endpoint is RouteEndpoint routeEndpoint &&
                     routeEndpoint.Metadata.GetMetadata<MethodInfo>() is { } methodInfo &&
-                    routeEndpoint.Metadata.GetMetadata<IHttpMethodMetadata>() is { } httpMethodMetadata)
+                    routeEndpoint.Metadata.GetMetadata<IHttpMethodMetadata>() is { } httpMethodMetadata &&
+                    (routeEndpoint.Metadata.GetMetadata<ISuppressApiMetadata>() == null || 
+                    routeEndpoint.Metadata.GetMetadata<ISuppressApiMetadata>() is { SuppressApi: false} ))
                 {
                     // REVIEW: Should we add an ApiDescription for endpoints without IHttpMethodMetadata? Swagger doesn't handle
                     // a null HttpMethod even though it's nullable on ApiDescription, so we'd need to define "default" HTTP methods.

src/Mvc/Mvc.ApiExplorer/test/EndpointMetadataApiDescriptionProviderTest.cs

@@ -409,6 +409,28 @@ public void RespectsProducesWithGroupNameExtensionMethod()
             Assert.Equal(endpointGroupName, apiDescription.GroupName); 
         }
 
+        [Fact]
+        public void RespectsSuppressApiMethod()
+        {
+            // Arrange
+            var builder = new TestEndpointRouteBuilder(new ApplicationBuilder(null));
+            builder.MapGet("/api/todos", () => "").Produces<InferredJsonClass>().SuppressApi();
+            var context = new ApiDescriptionProviderContext(Array.Empty<ActionDescriptor>());
+            
+            var endpointDataSource = builder.DataSources.OfType<EndpointDataSource>().Single();
+            var hostEnvironment = new HostEnvironment
+            {
+                ApplicationName = nameof(EndpointMetadataApiDescriptionProviderTest)
+            };
+            var provider = new EndpointMetadataApiDescriptionProvider(endpointDataSource, hostEnvironment, new ServiceProviderIsService());
+
+            // Act
+            provider.OnProvidersExecuting(context);
+
+            // Assert
+            Assert.Empty(context.Results);
+        }
+
         private IList<ApiDescription> GetApiDescriptions(
             Delegate action,
             string pattern = null,

src/Mvc/Mvc.Core/src/Builder/OpenApiEndpointConventionBuilderExtensions.cs

@@ -3,6 +3,7 @@
 
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Routing;
 
 namespace Microsoft.AspNetCore.Http
 {
@@ -11,6 +12,19 @@ namespace Microsoft.AspNetCore.Http
     /// </summary>
     public static class OpenApiEndpointConventionBuilderExtensions
     {
+        /// <summary>
+        /// Adds metadata to support suppressing OpenAPI documentation from
+        /// being generated for this endpoint.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
+        public static IEndpointConventionBuilder SuppressApi(this IEndpointConventionBuilder builder)
+        {
+            builder.WithMetadata(new SuppressApiMetadata());
+
+            return builder;
+        }
+
         /// <summary>
         /// Adds metadata indicating the type of response an endpoint produces.
         /// </summary>