如何配置Swashbuckle仅识别带有ApiControllerAttribute的控制器？

嘿，这个需求我之前做项目时也碰到过，Swashbuckle默认扫描所有控制器确实有点冗余，不过它提供了很灵活的过滤机制，下面给你分享两种最实用的实现方式：

方法一：使用IApiDescriptionFilter（推荐，性能更优） #

这种方式会在Swashbuckle生成API描述的阶段就过滤掉不符合要求的控制器，比生成文档后再移除要高效得多。

首先创建一个自定义过滤器类：

using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.SwaggerGen;

public class ApiControllerOnlyFilter : IApiDescriptionFilter
{
    public bool Apply(ApiDescription apiDescription, SchemaRepository schemaRepository)
    {
        // 尝试获取当前操作对应的控制器描述器
        var controllerActionDescriptor = apiDescription.ActionDescriptor as ControllerActionDescriptor;
        if (controllerActionDescriptor == null) return false;

        // 检查控制器是否带有ApiController特性
        return controllerActionDescriptor.ControllerTypeInfo
            .GetCustomAttributes(typeof(ApiControllerAttribute), inherit: true)
            .Any();
    }
}

然后在Swagger服务配置中注册这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 添加自定义过滤器
    c.ApiDescriptionFilter<ApiControllerOnlyFilter>();
    
    // 你的其他Swagger配置（比如文档信息、安全方案等）
});

方法二：使用IDocumentFilter #

如果因为版本原因无法使用IApiDescriptionFilter（比如旧版Swashbuckle），可以用这种方式在文档生成完成后，移除不属于ApiController的路径：

创建文档过滤器类：

using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.SwaggerGen;

public class ApiControllerOnlyDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 遍历所有路径，逐一检查对应的控制器是否符合要求
        foreach (var pathEntry in swaggerDoc.Paths.ToList())
        {
            // 获取当前路径对应的API描述
            var apiDescription = context.ApiDescriptions
                .FirstOrDefault(desc => desc.Id == pathEntry.Value.Operations.Values.First()?.OperationId);
            if (apiDescription == null)
            {
                swaggerDoc.Paths.Remove(pathEntry.Key);
                continue;
            }

            var controllerActionDescriptor = apiDescription.ActionDescriptor as ControllerActionDescriptor;
            if (controllerActionDescriptor?.ControllerTypeInfo
                .GetCustomAttributes(typeof(ApiControllerAttribute), true)
                .Any() != true)
            {
                swaggerDoc.Paths.Remove(pathEntry.Key);
            }
        }
    }
}

注册方式类似：

builder.Services.AddSwaggerGen(c =>
{
    c.DocumentFilter<ApiControllerOnlyDocumentFilter>();
    // 其他配置...
});

额外提示 #

如果你的API控制器还有其他统一特征（比如都在某个命名空间下），可以在过滤器里结合这些条件一起判断，进一步缩小范围，但直接检查ApiController特性是最精准的方式，毕竟这是官方标记API控制器的标准方式。

内容的提问来源于stack exchange，提问作者Haytam