.NET 8中ASP.Versioning路由版本化与Swagger构建失败问题

问题详情 #

• 原Microsoft.AspNetCore.MVC已弃用，改用ASP.Versioning实现API版本控制
• 控制器级别配置[Route("api/v{version:apiVersion}/metrics/setup")] + [ApiVersion("1.0")]，端点使用[HttpGet("locations")]
• 父路由中的{version:apiVersion}未被实际版本号替换，导致Swagger构建失败；但在.NET 6中使用旧版Microsoft.AspNetCore包时无此问题

解决方案 #

1. 正确配置ASP.Versioning服务 #

在Program.cs中必须完成API版本服务的完整注册，重点启用路由版本占位符替换：

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.UseApiBehavior = true;
})
.AddMvc()
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    // 核心配置：替换路由中的版本占位符
    options.SubstituteApiVersionInUrl = true;
});

2. 修正控制器基类 #

确保控制器继承ControllerBase（ASP.Versioning官方推荐），而非旧版ApiController：

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/metrics/setup")]
public sealed class LookupsController : ControllerBase
{
    [HttpGet("locations")]
    public async Task<IActionResult> GetAllLocationsAsync(CancellationToken cancellationToken)
    {
        // 业务逻辑实现
        return Ok();
    }
}

3. 适配Swagger生成器 #

配置Swagger生成器，为每个API版本生成对应文档：

builder.Services.AddSwaggerGen(options =>
{
    var apiVersionProvider = builder.Services.BuildServiceProvider()
        .GetRequiredService<IApiVersionDescriptionProvider>();

    foreach (var desc in apiVersionProvider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(
            desc.GroupName,
            new OpenApiInfo
            {
                Title = "Metrics API",
                Version = desc.ApiVersion.ToString()
            });
    }
});

4. 确认中间件顺序 #

确保中间件注册顺序正确，Swagger中间件需放在路由和授权之后：

app.UseRouting();
app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
});

// 注册Swagger UI
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());
    }
});

关键注意点 #

• SubstituteApiVersionInUrl是解决路由版本占位符未替换的核心，必须设置为true
• 确保安装最新稳定版的Asp.Versioning.Mvc和Asp.Versioning.Mvc.ApiExplorer包
• 完全移除旧版Microsoft.AspNetCore.Mvc.Versioning相关依赖，避免组件冲突

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