Add IgnoreApi() extension method for IEndpointConventionBuilder

[martincostello]

Background and Motivation

Related to #34061, if using minimal hosting with minimal actions and Swashbuckle and it is possible to hide actions from API Explorer using the [ApiExplorerSettings] attribute (which doesn't work right now, see also #34065), it would be a quality-of-life improvement to the API surface to add an extension method for IEndpointConventionBuilder to make it require less verbose code to hide it.

Proposed API

Add a new extension method to the Microsoft.AspNetCore.Mvc.ApiExplorer assembly with a name something along the lines of IgnoreApi():

namespace Microsoft.AspNetCore.Builder
{
+    public static class ApiExplorerEndpointConventionBuilderExtensions
+    {
+       public static TBuilder IgnoreApi<TBuilder>(this TBuilder builder) where TBuilder : IEndpointConventionBuilder;
+    }
}

The implementation would be something like this:

using Microsoft.AspNetCore.Mvc;

namespace Microsoft.AspNetCore.Builder
{
    /// <summary>
    /// API Explorer extension methods for <see cref="IEndpointConventionBuilder"/>.
    /// </summary>
    public static class ApiExplorerEndpointConventionBuilderExtensions
    {
        private static readonly ApiExplorerSettingsAttribute _ignoreApiMetadata = new()
        {
            IgnoreApi = true
        };

        /// <summary>
        /// Ignores the endpoint(s) from the API Explorer.
        /// </summary>
        /// <param name="builder">The endpoint convention builder.</param>
        /// <returns>The original convention builder parameter.</returns>
        public static TBuilder IgnoreApi<TBuilder>(this TBuilder builder) where TBuilder : IEndpointConventionBuilder
        {
            builder.Add(endpointBuilder =>
            {
                endpointBuilder.Metadata.Add(_ignoreApiMetadata);
            });
            return builder;
        }
    }
}

Usage Examples

var builder = WebApplication.CreateBuilder(args);

// Configure application...

var app = builder.Build();

// Redirect to Swagger documentation
app.MapGet("/api", () => Results.Redirect("/swagger-ui/index.html"))
   .IgnoreApi();

// Configure other endpoints...

app.Run();

Alternative Designs

No alternative designs considered, this is just API sugar to remove the need to use verbose way of doing this using the existing APIs, similar to the existing AllowAnonymous(), RequireAuthorization(), RequireCors(), RequireHost() and WithDisplayName() extension methods:

builder.MapGet("/api", () => Results.Redirect("/swagger-ui/index.html"))
       .WithMetadata(new ApiExplorerSettingsAttribute { IgnoreApi = true });

Risks

None that I'm aware of, other than potential conflicts with user-defined application extension methods of the same name.

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

[DamianEdwards]

Swashbuckle's default logic for whether to include an API in a given OpenAPI document is based on ApiDescription.GroupName today. To get the desired experience discussed here it should be updated to also look at whatever new metadata we add to indicate that an endpoint should be excluded when observing API explorer data.

Thanks for contacting us.

We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.