ASP.NET Core 7 Web API版本化路由定义及Swagger显示问题求助

问题1：固定路由触发UnsupportedApiVersion错误 #

使用固定路由[Route("api/v2/Subscription")]时，API版本化中间件无法自动识别路由中的版本标识，导致判定请求版本不被支持。解决方式：

• 给目标控制器添加[ApiVersion("2.0")]属性，明确绑定该控制器对应的API版本；若需支持多版本，可添加多个属性，如[ApiVersion("1.0"), ApiVersion("2.0")]
• 确保Program.cs中的ApiVersioning配置启用URL段版本读取（默认已启用，显式配置可避免歧义）：

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

问题2：模板路由下Swagger UI显示路由不符合预期 #

使用[Route("api/v{version:apiVersion}/Subscription")]时，Swagger默认会保留路由中的{version}占位符，需通过文档过滤器替换为具体版本号：

1. 在Program.cs的Swagger生成配置中，添加自定义DocumentFilter：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    options.SwaggerDoc("v2", new OpenApiInfo { Title = "你的API名称", Version = "v2" });

    options.DocumentFilter<ReplaceVersionPlaceholderFilter>();
});

// 实现版本占位符替换过滤器
public class ReplaceVersionPlaceholderFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        var updatedPaths = new OpenApiPaths();
        foreach (var pathEntry in swaggerDoc.Paths)
        {
            var newPath = pathEntry.Key.Replace("{version}", swaggerDoc.Info.Version);
            updatedPaths.Add(newPath, pathEntry.Value);
        }
        swaggerDoc.Paths = updatedPaths;
    }
}

2. 确保控制器上的[ApiVersion]属性与Swagger文档版本一一对应，例如v2控制器标注[ApiVersion("2.0")]
3. 配置Swagger UI时指定多版本入口：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
});

额外注意 #

若同时混用固定路由与模板路由，需保证每个控制器的路由规则和[ApiVersion]属性严格匹配，避免版本识别冲突。

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