.NET8升级后ApiVersionNeutral导致Swagger显示{version}参数的问题及解决

问题描述 #

项目从.NET Core 3.1升级至.NET 8，将版本控制包从Microsoft.AspNetCore.Mvc.Versioning替换为Asp.Versioning.Mvc后出现异常：

• 标记[ApiVersionNeutral]特性的控制器，Swagger端点显示为/v{version}/GetUser/{userId}，路由中的{version}被识别为普通参数；
• 若将[ApiVersionNeutral]替换为[ApiVersion("1.0")]，端点显示恢复正常：/v1/GetUser/{userId}；
• 已配置正确的基础ApiVersioning选项：

services.AddApiVersioning(c =>
{
   c.ReportApiVersions = true;
   c.DefaultApiVersion = new ApiVersion(1, 0);
   c.AssumeDefaultVersionWhenUnspecified = true;
});

控制器代码示例：

[ApiController]
[ApiVersionNeutral]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("~/v{version:apiVersion}/[controller]")]
public class SampleController : ControllerBase
{
   [HttpGet("{userId}", Name = "GetUser")]
   public async Task<ActionResult<UserResponseModel>> GetUser([FromRoute] int userId)
   {
      // 业务逻辑实现
   }
}

原因分析 #

Asp.Versioning.Mvc包对ApiVersionNeutral特性的默认处理逻辑与旧包不同：默认情况下，它不会为标记为无版本的控制器解析路由中的{version:apiVersion}约束，导致Swagger无法识别该版本参数的特殊含义，进而将其当作普通路由参数展示。

解决方案 #

在ApiVersioning配置中添加ApiExplorer的扩展配置，开启AddApiVersionParametersWhenVersionNeutral = true，让工具为ApiVersionNeutral控制器也处理路由中的版本参数：

services.AddApiVersioning(c =>
{
   c.ReportApiVersions = true;
   c.DefaultApiVersion = new ApiVersion(1, 0);
   c.AssumeDefaultVersionWhenUnspecified = true;
})
.AddApiExplorer(options =>
{
   options.AddApiVersionParametersWhenVersionNeutral = true;
});

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