Minimal API集成Swagger切换版本时端点显示错误问题

问题根源 #

你当前的路由配置里，前三个端点（RunProcess、GetParamsByName、GetAllProcedures）未指定具体API版本，默认会被所有版本（v1和v2）包含，导致切换到v2时，这些v1的端点也会显示出来。只有最后一个Mew端点明确指定了MapToApiVersion(2)，属于v2专属。

步骤1：修正路由配置 #

给版本1的三个端点添加MapToApiVersion(1)，明确它们的版本归属：

public override void AddRoutes(IEndpointRouteBuilder app)
{
    _vs = app.NewApiVersionSet()
        .HasApiVersion(new ApiVersion(1))
        .HasApiVersion(new ApiVersion(2))
        .Build();

    // 版本1专属端点
    app.MapPost("/{friendlyProcedureName}", RunProcess)
        .WithApiVersionSet(_vs)
        .MapToApiVersion(1); // 新增版本指定
    
    app.MapGet("/{friendlyProcedureName}/Params", GetParamsByName)
        .WithApiVersionSet(_vs)
        .MapToApiVersion(1); // 新增版本指定

    app.MapGet("/",  GetAllProcedures)
        .WithApiVersionSet(_vs)
        .MapToApiVersion(1); // 新增版本指定

    // 版本2专属端点
    app.MapGet("/", Mew)
        .WithApiVersionSet(_vs)
        .WithOpenApi()
        .MapToApiVersion(2);
}

步骤2：配置Swagger的DocInclusionPredicate #

在Swagger配置中，通过DocInclusionPredicate过滤掉不属于当前文档版本的端点，确保每个版本只显示对应端点：

services.AddSwaggerGen(options =>
{
    // 注册v1和v2文档
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    options.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });

    // 配置文档包含规则
    options.DocInclusionPredicate((docVersion, apiDesc) =>
    {
        var metadata = apiDesc.ActionDescriptor.EndpointMetadata;
        var apiVersionMetadata = metadata.OfType<ApiVersionMetadata>().FirstOrDefault();
        if (apiVersionMetadata == null)
            return false;
        
        // 检查文档版本是否匹配端点声明的版本
        return apiVersionMetadata.DeclaredApiVersions.Any(v => v.ToString() == docVersion);
    });
});

完成以上配置后，Swagger UI切换到v2时就只会显示Mew这一个端点，v1则显示对应的3个端点。

内容的提问来源于stack exchange，提问作者James Andrew Smith