如何在ASP.NET Core 6 Web API中实现SwaggerUI多级分组？

1. 创建自定义分组特性 #

定义一个特性类，用来标记控制器所属的模块和版本：

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
public class ApiGroupAttribute : Attribute
{
    public string Module { get; }
    public string Version { get; }

    public ApiGroupAttribute(string module, string version)
    {
        Module = module;
        Version = version;
    }

    // 生成带层级的分组名称，用斜杠分隔可让SwaggerUI自动生成折叠层级
    public string GetGroupName() => $"{Module}/{Version}";
}

2. 为控制器标记分组特性 #

在每个控制器上添加该特性，指定对应的模块和版本：

[ApiGroup("Module A", "V1")]
[ApiController]
[Route("api/v1/moduleA")]
public class ModuleAV1Controller : ControllerBase
{
    // 接口实现代码
}

[ApiGroup("Module A", "V2")]
[ApiController]
[Route("api/v2/moduleA")]
public class ModuleAV2Controller : ControllerBase
{
    // 接口实现代码
}

[ApiGroup("Module B", "V1")]
[ApiController]
[Route("api/v1/moduleB")]
public class ModuleBV1Controller : ControllerBase
{
    // 接口实现代码
}

3. 配置Swagger生成器 #

在Program.cs中配置Swagger，自动扫描控制器的自定义特性并创建对应分组的文档：

builder.Services.AddSwaggerGen(c =>
{
    // 遍历所有程序集，提取控制器的分组信息
    foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
    {
        var controllerTypes = assembly.GetTypes()
            .Where(t => t.IsClass && !t.IsAbstract && typeof(ControllerBase).IsAssignableFrom(t));

        foreach (var controllerType in controllerTypes)
        {
            var groupAttr = controllerType.GetCustomAttribute<ApiGroupAttribute>();
            if (groupAttr == null) continue;

            var groupName = groupAttr.GetGroupName();
            // 为每个分组创建Swagger文档
            c.SwaggerDoc(groupName, new OpenApiInfo
            {
                Title = $"{groupAttr.Module} API {groupAttr.Version}",
                Version = groupAttr.Version,
                Description = $"{groupAttr.Module} 模块 {groupAttr.Version} 版本接口文档"
            });
        }
    }

    // 可选：添加XML注释支持，需在项目属性中启用XML文档文件生成
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
    c.IncludeXmlComments(xmlFilePath);
});

4. 配置SwaggerUI显示多级分组 #

在Program.cs中配置SwaggerUI，加载所有生成的分组文档并设置显示样式：

app.UseSwaggerUI(c =>
{
    var swaggerProvider = app.Services.GetRequiredService<ISwaggerProvider>();
    var docs = swaggerProvider.GetSwaggerDocs();
    
    // 为每个分组添加Swagger端点
    foreach (var doc in docs)
    {
        c.SwaggerEndpoint($"/swagger/{doc.Key}/swagger.json", doc.Key);
    }

    // 设置文档默认折叠，仅显示分组层级
    c.DocExpansion(DocExpansion.List);
});

效果说明 #

• 使用斜杠分隔的分组名称会让SwaggerUI自动生成折叠层级，显示效果为：
  • Module A
    • V1
    • V2
  • Module B
    • V1
• 如果需要保持Module A - V1的平级显示格式，只需修改ApiGroupAttribute中的GetGroupName方法为：

public string GetGroupName() => $"{Module} - {Version}";

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