.NET 8中ApiVersion特性在Swagger页面失效问题咨询

近期将WebAPI升级至.NET 8，测试时发现ApiVersion特性在Swagger页面无法正常工作——版本号无法像.NET 7中那样自动填充。

我的SubscriptionController代码如下：

[ApiVersion("1.0")]
[Route("v{version:apiVersion}/api/[controller]")]
[ApiController]
[Authorize]
public class SubscriptionController(ISubscriptionDataService subscriptionDataService, 
                                    IConfigurationService configurationService) : ControllerBase

此前.NET 7默认模板的WeatherForecastController可自动填充版本号，代码如下：

[ApiVersion("1.0")]
[Route("v{version:apiVersion}/api/[controller]")]
[ApiController]
[Authorize]
public class WeatherForecastController : ControllerBase

Program.cs中原本的版本配置代码为：

private static void AddApiVersioning(IServiceCollection services)
{
    services.AddApiVersioning(options =>
    {
        options.AssumeDefaultVersionWhenUnspecified = false;
        options.ReportApiVersions = false;
    });

    services.AddVersionedApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });
}

编辑1：适配弃用包后的配置调整 #

由于相关包已弃用（Microsoft.AspNetCore.Mvc.Versioning替换为Asp.Versioning.Mvc，Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer替换为Asp.Versioning.Mvc.ApiExplorer），我调整了Program.cs配置：

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = false;
    options.ReportApiVersions = false;
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl=true;
});


var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    var descriptions = app.DescribeApiVersions();
    foreach (var description in descriptions)
    {
        var url = $"/swagger/{description.GroupName}/swagger.json";
        var name = description.GroupName.ToUpperInvariant();
        options.SwaggerEndpoint(url, name);
    }
});

同时将控制器中的[ApiVersion("1.0")]替换为[Asp.Versioning.ApiVersion("1.0")]。该配置在微软WebAPI模板中有效，但结合其他Swagger特性和中间件时，仍需手动输入版本号。

编辑2：类级+方法级多路由配置在Swagger中失效 #

经测试发现，类级和方法级同时配置多路由的方式在Swagger中失效，即使在微软测试项目中也是如此：

Swagger中失效的代码 #

using Microsoft.AspNetCore.Mvc;

namespace webapitest.Controllers;

[Asp.Versioning.ApiVersion("1.0")]
[Route("v{version:apiVersion}/api/[controller]")]
[ApiController]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    [HttpGet]
    [Route("/Weather")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
    }
}

Swagger中有效的代码 #

using Microsoft.AspNetCore.Mvc;

namespace webapitest.Controllers;

[Asp.Versioning.ApiVersion("1.0")]
[ApiController]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    [HttpGet]
    [Route("v{version:apiVersion}/api/[controller]/Weather")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
    }
}

请问为何这种写法不再生效？

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