如何在ASP.NET Core Swagger UI中标记指定API版本为已弃用状态

实现方案 #

下面是Swashbuckle官方推荐的标准实现方式，无需修改端点显示文案，也不需要给Controller加[Obsolete]特性，就能给指定弃用版本的API添加统一标识：

步骤1：实现自定义DocumentFilter #

通过IDocumentFilter可以直接修改指定版本的Swagger文档元数据，统一添加弃用标记：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using Asp.Versioning.ApiExplorer;

public class DeprecatedVersionDocumentFilter : IDocumentFilter
{
    private readonly IApiVersionDescriptionProvider _versionProvider;

    public DeprecatedVersionDocumentFilter(IApiVersionDescriptionProvider versionProvider)
    {
        _versionProvider = versionProvider;
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 匹配当前Swagger文档对应的API版本
        var currentVersionDesc = _versionProvider.ApiVersionDescriptions
            .FirstOrDefault(v => v.GroupName == context.DocumentName);
        
        if (currentVersionDesc is not { IsDeprecated: true }) return;
        
        // 给当前版本Swagger页顶部添加醒目的弃用提示横幅
        swaggerDoc.Info.Description = $"""
            <div style="color:#dc3545;font-weight:bold;padding:12px;border:1px solid #dc3545;border-radius:4px;margin-bottom:20px;">
            ⚠️ 该API版本已正式弃用，请尽快切换到最新版本使用
            </div>
            {swaggerDoc.Info.Description}
        """;
        
        // 给当前版本下所有接口统一标记为弃用，Swagger UI会原生显示弃用标识，不会产生删除线
        foreach (var pathItem in swaggerDoc.Paths.Values)
        {
            foreach (var operation in pathItem.Operations.Values)
            {
                operation.Deprecated = true;
            }
        }
    }
}

步骤2：注册DocumentFilter #

在Swagger服务注册逻辑中添加上述过滤器：

// Startup.cs 或 Program.cs 中的AddSwaggerGen配置
builder.Services.AddSwaggerGen(options =>
{
    // 保留你原有的Swagger配置，包括版本、安全校验等逻辑
    // 注册自定义弃用版本过滤器
    var versionProvider = builder.Services.BuildServiceProvider()
        .GetRequiredService<IApiVersionDescriptionProvider>();
    options.DocumentFilter<DeprecatedVersionDocumentFilter>(versionProvider);
});

步骤3：保留原有SwaggerUI配置 #

你的Swagger端点配置无需做任何修改，不用加(DEPRECATED)后缀，下拉框显示和原来完全一致：

app.UseSwaggerUI(options =>
{
    foreach (var desc in apiVersionDescriptionProvider.ApiVersionDescriptions.OrderByDescending(a => a.ApiVersion))
    {
        options.SwaggerEndpoint($"{Configuration["PathBase"]}/swagger/{desc.GroupName}/swagger.json",
            desc.GroupName.ToUpperInvariant());
    }
});

方案优势 #

• 完全基于Swashbuckle官方扩展能力实现，兼容性强，属于标准实现方式
• 无需修改业务代码，不会给Controller添加[Obsolete]特性产生不必要的删除线
• 提示效果更直观：用户切换到弃用版本时，页面顶部会显示红色提示横幅，每个接口也会有原生的弃用标识
• 不修改原有端点下拉框的显示文案，符合你的需求

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