ASP.NET Core Minimal API中IsApiVersionNeutral使用问题咨询

需求回顾 #

• /GetMessage：仅支持2.0版本
• /GetText：版本中立接口，支持无版本、1.0、2.0、3.0版本

异常问题分析与解决 #

问题1：/GetMessage响应头返回全局所有版本 #

api-supported-versions: 1.0,2.0,3.0是全局注册的版本集合，默认版本控制中间件会把全局定义的所有版本返回在响应头里。要让单个接口返回专属支持版本，需做以下调整：

1. 全局注册版本时，确保启用版本报告并配置所有支持的版本：

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(2, 0);
    // 根据实际使用的版本传递方式配置读取器，示例用查询参数
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
    // 注册所有支持的版本
    options.SupportedApiVersions.Add(new ApiVersion(1, 0));
    options.SupportedApiVersions.Add(new ApiVersion(2, 0));
    options.SupportedApiVersions.Add(new ApiVersion(3, 0));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

2. 给/GetMessage明确绑定仅支持的2.0版本，中间件会自动识别并返回对应版本的响应头：

app.MapGet("/GetMessage", () => "Hello from v2.0")
   .MapToApiVersion(new ApiVersion(2, 0));

问题2：/GetText仅支持v2.0，1.0/3.0请求返回404 #

版本中立接口必须明确标记为版本中立，否则会默认使用全局默认版本（此处为2.0），导致其他版本请求无法匹配。在Minimal API中，需用WithApiVersionNeutral()方法标记：

app.MapGet("/GetText", () => "Hello from neutral version")
   .WithApiVersionNeutral();

同时确保全局已注册1.0、2.0、3.0所有版本，且版本读取器配置正确（比如用查询参数需带?api-version=1.0，用URL路径需符合/v1.0/GetText格式）。

完整核心代码示例 #

var builder = WebApplication.CreateBuilder(args);

// 配置版本控制服务
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(2, 0);
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
    options.SupportedApiVersions.Add(new ApiVersion(1, 0));
    options.SupportedApiVersions.Add(new ApiVersion(2, 0));
    options.SupportedApiVersions.Add(new ApiVersion(3, 0));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// 配置Swagger（按需保留）
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    var apiVersionProvider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var desc in apiVersionProvider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(desc.GroupName, new OpenApiInfo { Title = "Versioned API", Version = desc.ApiVersion.ToString() });
    }
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        var apiVersionProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
        foreach (var desc in apiVersionProvider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{desc.GroupName}/swagger.json", desc.GroupName.ToUpperInvariant());
        }
    });
}

app.UseHttpsRedirection();

// 绑定/GetMessage到v2.0
app.MapGet("/GetMessage", () => Results.Ok("Hello from v2.0"))
   .MapToApiVersion(new ApiVersion(2, 0))
   .WithName("GetMessage");

// 标记/GetText为版本中立
app.MapGet("/GetText", () => Results.Ok("Hello from neutral version"))
   .WithApiVersionNeutral()
   .WithName("GetText");

app.Run();

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