在ASP.NET中通过Swagger全局配置API标签顺序及描述

一、实现标签全局排序 #

你已经添加了TagOrderFilter，需要完善过滤器的具体实现来指定全局标签排序规则：

1. 创建TagOrderFilter类，自定义接口层面的标签排序逻辑：

public class TagOrderFilter : IOperationFilter
{
    // 按业务需求定义标签的显示顺序
    private readonly List<string> _tagOrder = new List<string>
    {
        "Finishing the import",
        "标签2",
        "标签3",
        // 依次添加你所有的6-7个标签
    };

    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Tags != null && operation.Tags.Any())
        {
            // 按预设顺序重新排列当前接口的标签
            var orderedTags = operation.Tags.OrderBy(t => _tagOrder.IndexOf(t.Name)).ToList();
            operation.Tags.Clear();
            operation.Tags.AddRange(orderedTags);
        }
    }
}

2. 补充全局标签分组的排序过滤器，确保Swagger UI的标签列表也按指定顺序展示：

public class TagDocumentOrderFilter : IDocumentFilter
{
    private readonly List<string> _tagOrder;

    public TagDocumentOrderFilter(List<string> tagOrder)
    {
        _tagOrder = tagOrder;
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 重新排序全局标签集合
        var orderedTags = swaggerDoc.Tags.OrderBy(t => _tagOrder.IndexOf(t.Name)).ToList();
        swaggerDoc.Tags.Clear();
        swaggerDoc.Tags.AddRange(orderedTags);
    }
}

二、为标签添加全局描述 #

通过DocumentFilter在全局层面给每个标签绑定描述，无需手动修改生成的YAML：

创建TagDescriptionFilter类：

public class TagDescriptionFilter : IDocumentFilter
{
    // 为每个标签配置对应的描述文本
    private readonly Dictionary<string, string> _tagDescriptions = new Dictionary<string, string>
    {
        {"Finishing the import", "负责导入流程的收尾操作，包含状态更新、结果校验等逻辑"},
        {"标签2", "这是第二个业务模块的接口集合描述"},
        {"标签3", "这是第三个业务模块的接口集合描述"},
        // 依次为所有标签添加描述
    };

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var tag in swaggerDoc.Tags)
        {
            if (_tagDescriptions.TryGetValue(tag.Name, out var description))
            {
                tag.Description = description;
            }
        }
    }
}

三、整合到Swagger配置中 #

修改你的Program.cs代码，注册所有过滤器并传入标签顺序：

services.AddEndpointsApiExplorer();
// 定义全局标签顺序列表
var tagOrder = new List<string>
{
    "Finishing the import",
    "标签2",
    "标签3",
    // 按实际需求添加所有标签
};

services.AddSwaggerGen(c =>
{
    c.EnableAnnotations();
    // 注册接口标签排序过滤器
    c.OperationFilter<TagOrderFilter>();
    // 注册全局标签分组排序过滤器
    c.DocumentFilter<TagDocumentOrderFilter>(tagOrder);
    // 注册标签描述过滤器
    c.DocumentFilter<TagDescriptionFilter>();

    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "InboundApp",
        Version = "v1",
        Description = "bla",
    });
});

注意事项 #

• 所有业务中用到的标签都要在_tagOrder和_tagDescriptions中定义，确保排序和描述覆盖所有场景
• 若控制器或方法绑定了多个标签，过滤器会自动按预设顺序排列这些标签
• 生成的OpenAPI YAML/JSON文件会自动带上标签的描述和正确排序，无需手动修改

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