如何通过Swashbuckle实现SwaggerUI中Entities标签的嵌套控制器结构

要实现「Entities->控制器->API方法」的嵌套层级结构，核心是让SwaggerUI识别标签的层级关系，通过自定义操作过滤器批量设置带层级前缀的标签即可解决，具体步骤如下：

1. 自定义操作过滤器（批量设置层级标签） #

创建一个IOperationFilter实现类，自动给每个API操作添加带父标签前缀的标签：

using Microsoft.AspNetCore.Mvc.Controllers;
using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;

public class EntityHierarchyTagFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 获取控制器名称（自动去除Controller后缀）
        var controllerName = context.ApiDescription.ActionDescriptor is ControllerActionDescriptor descriptor
            ? descriptor.ControllerName.Replace("Controller", "")
            : "UnknownController";

        // 清空默认标签，添加层级标签（用|作为层级分隔符）
        operation.Tags.Clear();
        operation.Tags.Add(new OpenApiTag { Name = $"Entities|{controllerName}" });
    }
}

2. 注册过滤器到SwaggerGen #

在Program.cs的Swagger配置中注册这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 保留你原有的Swagger配置（比如文档信息、XML注释等）
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

    // 注册自定义层级标签过滤器
    c.OperationFilter<EntityHierarchyTagFilter>();
});

3. 配置SwaggerUI识别层级分隔符 #

默认SwaggerUI支持用|作为标签层级分隔符，若需要显式指定或调整，可在SwaggerUI配置中添加：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    // 显式指定标签层级分隔符（可选，默认已支持|）
    c.TagSelectorSeparator("|");
    // 可选：设置默认展开状态，比如None是全部折叠，List是展开标签层级
    c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);
});

4. 可选：灵活控制哪些控制器加入Entities层级 #

如果不是所有控制器都需要放到Entities下，可以通过自定义特性来筛选：

第一步：定义标记特性 #

[AttributeUsage(AttributeTargets.Class)]
public class EntityGroupAttribute : Attribute
{
    // 可自定义父组名称，默认是Entities
    public string ParentGroupName { get; } = "Entities";
}

第二步：给目标控制器添加特性 #

[EntityGroup]
public class EmployeesController : ControllerBase
{
    // API方法...
}

[EntityGroup]
public class ProductsController : ControllerBase
{
    // API方法...
}

第三步：修改过滤器适配特性 #

public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
    var controllerDescriptor = context.ApiDescription.ActionDescriptor as ControllerActionDescriptor;
    if (controllerDescriptor == null) return;

    // 只处理标记了EntityGroup特性的控制器
    var groupAttr = controllerDescriptor.ControllerTypeInfo.GetCustomAttribute<EntityGroupAttribute>();
    if (groupAttr == null) return;

    var controllerName = controllerDescriptor.ControllerName.Replace("Controller", "");
    operation.Tags.Clear();
    operation.Tags.Add(new OpenApiTag { Name = $"{groupAttr.ParentGroupName}|{controllerName}" });
}

原理说明 #

之前直接设置所有方法的Tag为Entities，导致所有API都平铺在同一个标签下；而通过给标签添加父标签|子标签的格式，SwaggerUI会自动解析分隔符，将子标签嵌套到父标签下，从而实现你需要的层级结构。

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