.NET Core 3.1 C#多API版本场景下Swagger UI端点未正确分离问题

该问题由API版本控制组件与Swagger API探索器联动配置缺失、分组过滤逻辑不严谨导致，按以下步骤修改即可解决： #

步骤1：安装缺失的NuGet包 #

项目仅引入了API版本控制的基础包，缺少和Swagger联动的API探索扩展包，通过NuGet安装Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer，注意版本要和当前使用的Microsoft.AspNetCore.Mvc.Versioning包版本一致，.NET Core 3.1项目建议使用3.x版本的包。

步骤2：补充版本探索配置 #

修改Startup.cs中ConfigureServices方法的API版本控制配置，追加版本探索的相关配置：

services.AddApiVersioning(c =>
{
    c.DefaultApiVersion = new ApiVersion(1, 0);
    c.AssumeDefaultVersionWhenUnspecified = true;
    c.ReportApiVersions = true;
    c.ApiVersionReader = new UrlSegmentApiVersionReader();
})
// 新增以下版本探索配置
.AddVersionedApiExplorer(opt =>
{
    // 分组名格式：v + 版本号，比如v1、v2
    opt.GroupNameFormat = "'v'V";
    // 自动将路由中的版本占位符替换为实际版本号
    opt.SubstituteApiVersionInUrl = true;
});

步骤3：优化Swagger文档过滤逻辑 #

原有的DocInclusionPredicate仅通过GroupName判断存在识别误差，替换为通过控制器的ApiVersion特性直接匹配版本，修改AddSwaggerGen中的对应配置：

services.AddSwaggerGen(c =>
{
    // 原有SwaggerDoc配置保持不变
    c.SwaggerDoc("v1", new OpenApiInfo { /* 原有配置 */ });
    c.SwaggerDoc("v2", new OpenApiInfo { /* 原有配置 */ });
    
    c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
    // 替换原有DocInclusionPredicate逻辑
    c.DocInclusionPredicate((docName, apiDesc) =>
    {
        if (!apiDesc.TryGetMethodInfo(out var methodInfo)) 
            return false;
        
        // 获取当前接口所属控制器标注的所有版本号
        var apiVersions = methodInfo.DeclaringType
            .GetCustomAttributes(inherit: true)
            .OfType<ApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);
        
        // 匹配文档名称和版本号
        return apiVersions.Any(v => $"v{v.MajorVersion}" == docName);
    });
});

验证方法 #

修改完成后清理项目重新编译，启动后直接访问/swagger/v2/swagger.json，搜索v1版本的接口路径，确认不存在后再访问UI验证切换效果即可。
如果修改后仍有问题，可在DocInclusionPredicate中打断点，排查接口未被正确过滤的原因。 #

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