What is the recommended mechanism to ignore actions from Swagger with minimal actions?

[martincostello]

I've been playing around with using minimal actions to build a sample app that's a mix of API, Identity and Razor Pages, but exclusively using minimal actions to implement any endpoints in the app, not just the API. I'm currently using this with a daily build of the preview 7 SDK (6.0.100-preview.7.21330.1).

When plugging-in Swagger with the minimal configuration, all the minimal actions endpoints are returned in the Swagger documentation.

I've manually hidden things with the following code:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Todo API", Version = "v1" });

    options.DocInclusionPredicate(
        (_, description) => description.RelativePath?.StartsWith("api/", StringComparison.Ordinal) == true);
});

However what I would have liked to have done instead is to explicitly hide the actions using the ApiExplorerSettings attribute using the new support for attributes on lambdas, that doesn't seem to be working.

This is what I tried:

builder.MapPost("/signin", [ApiExplorerSettings(IgnoreApi = true)] () =>
    Results.Challenge(
        new AuthenticationProperties { RedirectUri = "/" },
        GitHubAuthenticationDefaults.AuthenticationScheme));

Another approach I've used in the past is the IActionModelConvention support, but that's part of MVC so doesn't appear to be valid either.

While the DocInclusionPredicate() approach works with a simple app, it doesn't feel like it would scale well from a maintenance point of view, particularly if the naming/paths weren't following a specific convention. It also doesn't seem possible to query for any decorated attributes (i.e. the ApiExplorerSettingsAttribute) from the ApiDescription passed to the method.

What is/will be the intended mechanism developers using minimal actions would use to hide specific actions from the API Explorer for use cases like Swagger?

[martincostello]

It's possible that using [ApiExplorerSettings] should work, but doesn't because the metadata on the endpoint isn't copied over.

I've opened #34065 as a draft that resolves that, assuming it's the correct thing to do.

[martincostello]

Having dug through how this works today for MVC, it looks like this is currently dealt with by ApplicationModel with the IApiExplorerModel implementation and the way that DefaultApplicationModelProvider implements IApplicationModelProvider which eventually goes through ApplicationModelConventions.ApplyConventions() to apply the built-in conventions that then use the IApiExplorerModels to apply all of the built-in IApplicationModelConvention implementations, which eventually result in things being suppressed when [ApiExplorerSettings(IgnoreApi = true)] is used.

ApplicationModel seems to be controller-centric though, so making it aware of arbitrary endpoints seems wrong, but not doing so means that all of the built-in conventions can't be applied to minimal actions.

The model doesn't support having multiple models either from what I can tell, so it doesn't look like having a parallel implementation that didn't care about controllers and operated in the registered endpoints would make much sense either.

TL;DR - It looks like #34065 wouldn't make [ApiExplorerSettings] Just Work™️, but it would make it possible for consuming applications to hide it manually with DocInclusionPredicate() when using Swashbuckle.AspNetCore. I'm not sure what the It Just Works™️ approach would need to be for minimal actions.

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.