如何实现ASP.NET Core API版本含主次版但路径仅保留主版？

错误原因 #

你遇到的UnsupportedApiVersion错误，根源是API版本控制系统默认会尝试匹配完整的版本号（如1.1），但你的路由硬编码了v1（仅主版本），系统会将其解析为版本1.0，与控制器标记的1.1不匹配，因此拒绝请求。

推荐配置方式 #

采用路由占位符+版本选择器的方案，既满足路由仅显示主版本的需求，又能让系统正确匹配控制器的完整版本。

1. 配置Program.cs中的API版本服务

修改AddApiVersioning的配置，添加版本读取规则、默认版本和自动版本选择逻辑：

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    // 设置默认版本为控制器标记的1.1
    options.DefaultApiVersion = new ApiVersion(1, 1);
    // 从URL段读取版本（对应路由中的{version}占位符）
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
    // 自动选择主版本下的最新次版本（如请求v1时匹配1.1）
    options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
    // 允许版本非精确匹配（兼容主版本请求）
    options.MatchExactly = false;
});

2. 修改控制器的路由模板

将硬编码的v1替换为版本占位符{version:apiVersion}，让API版本系统自动关联路由与控制器版本：

[ApiController]
[ApiVersion("1.1")]
// 使用版本占位符，路由会自动解析为/v1/WeatherForecast
[Route("v{version:apiVersion}/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new { Version = "1.1", Message = "Weather forecast data" });
    }
}

硬编码路由的备选方案（不推荐） #

如果必须保持路由硬编码为v1，可以通过以下配置让系统强制使用指定版本：

控制器修改

[ApiController]
[ApiVersion("1.1")]
[MapToApiVersion("1.1")]
[Route("v1/[controller]")]
public class WeatherForecastController : ControllerBase
{
    // ...
}

Program.cs配置

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 1);
    // 禁用从URL读取版本，依赖默认版本匹配
    options.ApiVersionReader = new NullApiVersionReader();
});

这种方式的弊端是扩展性差，后续新增版本时需要重复硬编码路由。

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