.net core/swagger - 生成 swagger.json 文件时如何绕过控制器文件？

Question

I have been handled a project and trying to add a swagger document for it. (using Swashbuckle.AspNetCore)

I should have configured everything right.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "HCP API", Version = "v1" });
    var xmlPath = Path.Combine(AppContext.BaseDirectory, "XXXXXXXX.WebForApi.xml");
    c.IncludeXmlComments(xmlPath);
});

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "HCP Api V1");
});

However, I've got an exception when generating the swagger.json file.

System.NotSupportedException: Ambiguous HTTP method for action - XXXXXXXXX.Frameworks.Users.ApiControllers.SystemUserController.ApiModel (XXXXXXXXX.Framework.Users). Actions require an explicit HttpMethod binding for Swagger 2.0
   at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.CreatePathItem(IEnumerable`1 apiDescriptions, ISchemaRegistry schemaRegistry)
   at System.Linq.Enumerable.ToDictionary[TSource,TKey,TElement](IEnumerable`1 source, Func`2 keySelector, Func`2 elementSelector, IEqualityComparer`1 comparer)
   at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.CreatePathItems(IEnumerable`1 apiDescriptions, ISchemaRegistry schemaRegistry)
   at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.GetSwagger(String documentName, String host, String basePath, String[] schemes)
   at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
   at Microsoft.AspNetCore.ResponseCaching.ResponseCachingMiddleware.Invoke(HttpContext httpContext)
   at Microsoft.AspNetCore.ResponseCompression.ResponseCompressionMiddleware.Invoke(HttpContext context)
   at Microsoft.AspNetCore.Server.IIS.Core.IISHttpContextOfT`1.ProcessRequestAsync()

The file caused this error is a DLL file which includes in the project via NuGet. (It's from a vendor company, I'm not sure that I was allowed to show its name.)

I have tried to add Filter to avoid this controller file, but it does not run into the filter code. I'm not sure I add it correctly.

It's anyway to solve this problem?

Answer 1

Yes, you need to add a filter to control this behavior. Here is some code which help you to include the filter.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    c.DocumentFilter<HideInDocsFilter>();
});

Here my pseudo filter code.

public class HideInDocsFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var apiDescription in context.ApiDescriptions)
        {
            if(apiDescription.RelativePath.Equals("SystemUser", System.StringComparison.OrdinalIgnoreCase))
            {
                var route = "/" + apiDescription.RelativePath.TrimEnd('/');
                swaggerDoc.Paths.Remove(route);
            }
        }
    }
}