filter out the APIs being documented by NSwag in ASP.NET Core MVC

[tugberkugurlu]

I am trying to filter out the APIs being documented by NSwag inside an ASP.NET Core MVC application but it seems to be failing so far. I used the following custom IActionDescriptorCollectionProvider which seems to be picked up by ASP.NET Core MVC but not by NSwag.

    public class CustomActionDescriptorCollectionProvider : IActionDescriptorCollectionProvider
    {
        private readonly ActionDescriptorCollectionProvider _actionDescriptorCollectionProvider;

        public CustomActionDescriptorCollectionProvider(IEnumerable<IActionDescriptorProvider> actionDescriptorProviders,
            IEnumerable<IActionDescriptorChangeProvider> actionDescriptorChangeProviders)
        {
            if (actionDescriptorProviders == null) throw new ArgumentNullException(nameof(actionDescriptorProviders));
            if (actionDescriptorChangeProviders == null) throw new ArgumentNullException(nameof(actionDescriptorChangeProviders));

            _actionDescriptorCollectionProvider = new ActionDescriptorCollectionProvider(actionDescriptorProviders, actionDescriptorChangeProviders);
        }

        public ActionDescriptorCollection ActionDescriptors
        {
            get
            {
                var filteredCollection = _actionDescriptorCollectionProvider.ActionDescriptors.Items.Where(descriptor =>
                {
                    return false;
                }).ToList();

                return new ActionDescriptorCollection(filteredCollection, _actionDescriptorCollectionProvider.ActionDescriptors.Version);
            }
        }
    }

Then, I registered this like below:

            services.AddSingleton<IActionDescriptorCollectionProvider, CustomActionDescriptorCollectionProvider>();

This is just for a sample as you can see it hides all the actions but with this I expected NSwag to document nothing.

What's the recommended way to filter out APIs to be documented in NSwag based on a condition? I can see the SwaggerIgnoreAttribute but I cannot apply that based on a condition.

[tugberkugurlu]

More info on how I ended up here: I can see that AspNetCoreToSwaggerMiddleware uses IApiDescriptionGroupCollectionProvider to get the list of APIs: https://github.com/RSuter/NSwag/blob/51146404ef3bcb134a54d0b689ba49dbc1b706a8/src/NSwag.AspNetCore/Middlewares/AspNetCoreToSwaggerMiddleware.cs#L42

When you look at the ApiDescriptionGroupCollectionProvider which is the default impl of IApiDescriptionGroupCollectionProvider, it uses IActionDescriptorCollectionProvider to get the list of actions. Therefore, I thought that it would be feasible to provide a custom implementation of IApiDescriptionGroupCollectionProvider and that would be taken into account by both MVC and NSwag. It doesn't seem to be the case so far.

[RicoSuter]

NSwag has two generators: One is completely reflection based (default) and the never one API explorer based (this one will eventually be the default). Either you use the reflection based generator and filter with an operation processor or you switch to the new generator: #999

i.e. UseSwagger*WithApiExplorer(), AspNetCoreToSwaggerGenerator, etc.

[RicoSuter]

Hmm ok, that is strange... maybe you have to deregister the old provider?

[tugberkugurlu]

i.e. UseSwagger*WithApiExplorer(), AspNetCoreToSwaggerGenerator, etc.

hmm, I cannot see WithApiExplorer option. Where exactly is this type?

[tugberkugurlu]

Either you use the reflection based generator and filter with an operation processor or you switch to the new generator

I would love to switch to a new generator if possible but cannot find how.

[RicoSuter]

See https://github.com/RSuter/NSwag/wiki/Middlewares

[RicoSuter]

Q: How did you integrate NSwag into your project?

[tugberkugurlu]

See https://github.com/RSuter/NSwag/wiki/Middlewares

Great, app.UseSwaggerWithApiExplorer and app.UseSwaggerUi3WithApiExplorer seems to be working 🚀

[tugberkugurlu]

Q: How did you integrate NSwag into your project?

I initially added these two calls during app startup:

            app.UseSwagger(typeof(Startup).GetTypeInfo().Assembly, settings =>
            {
                // ...
            });

            app.UseSwaggerUi3();

but now switched to UseSwaggerWithApiExplorer and UseSwaggerUi3WithApiExplorer.

[tugberkugurlu]

Thanks for the help @RSuter! I have also opened up dotnet/AspNetCore.Docs#6785 before. Would be lovely to provide documentation there about this. If I get my sample working, I can try to see if I can provide it there, too.

[RicoSuter]

Important: UseSwaggerUi3 also contains UseSwagger, no need to specify both (may cause problems) and in services you need to add AddSwagger()

[tugberkugurlu]

UseSwaggerUi3 also contains UseSwagger, no need to specify both

lovely, did that now!

in services you need to add AddSwagger()

Doing this now as well but it was working w/o this anyway 🤔

[RicoSuter]

AddSwagger() is only needed for the new UseSwagger*WithApiExplorer() methods