.NET 6升级API版本库后SwaggerUI URL版本自动填充失效求助

从旧版本的Microsoft.AspNetCore.Mvc.Versioning升级到Asp.Versioning.Mvc后，SwaggerUI无法自动填充版本号的核心原因是新版本的配置逻辑有调整，以下是需要补全或修正的关键配置：

1. 修正API版本控制核心服务配置 #

在Program.cs中注册版本控制服务时，必须明确配置版本读取方式和ApiExplorer的关键参数：

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    // 指定版本通过URL路径传递（适配你的路由模板）
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(options =>
{
    // 定义Swagger文档的版本分组格式（如v1、v2）
    options.GroupNameFormat = "'v'VVV";
    // 关键：自动替换URL中的版本占位符，让SwaggerUI能识别并填充
    options.SubstituteApiVersionInUrl = true;
});

其中SubstituteApiVersionInUrl是让Swagger自动填充版本号的核心开关，旧版本默认行为在新版本中需要显式开启。

2. 确保Swagger文档生成逻辑适配版本控制 #

你的ConfigureSwaggerOptions需要基于新版本的IApiVersionDescriptionProvider生成对应版本的Swagger文档，示例如下：

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider _apiVersionDescriptionProvider;

    public ConfigureSwaggerOptions(IApiVersionDescriptionProvider apiVersionDescriptionProvider)
    {
        _apiVersionDescriptionProvider = apiVersionDescriptionProvider;
    }

    public void Configure(SwaggerGenOptions options)
    {
        // 为每个API版本生成独立的Swagger文档
        foreach (var description in _apiVersionDescriptionProvider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(description.GroupName, CreateApiInfo(description));
        }

        // 保留你的XML注释等其他配置
        var xmlFilePath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
        options.IncludeXmlComments(xmlFilePath);
    }

    private OpenApiInfo CreateApiInfo(ApiVersionDescription description)
    {
        var info = new OpenApiInfo
        {
            Title = "你的API名称",
            Version = description.ApiVersion.ToString(),
            Description = $"API版本 {description.ApiVersion}"
        };

        if (description.IsDeprecated)
        {
            info.Description += " （此版本已废弃，请使用更高版本）";
        }

        return info;
    }
}

记得在Program.cs中注册这个配置类：

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

3. 修正SwaggerUI的端点配置 #

在Program.cs的中间件配置中，要确保SwaggerUI加载所有版本的文档，且端点路径与版本分组匹配：

app.UseSwaggerUI(options =>
{
    var apiVersionProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var description in apiVersionProvider.ApiVersionDescriptions)
    {
        // 端点路径要和ConfigureSwaggerOptions中生成的GroupName一致
        options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
    }
    // 可选：设置SwaggerUI的根路径
    options.RoutePrefix = string.Empty;
});

4. 验证控制器路由与版本特性 #

确保控制器上的路由模板和版本特性配置正确，示例：

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class CustomController : ControllerBase
{
    [MapToApiVersion("1.0")]
    [HttpGet]
    public IActionResult GetV1() => Ok("版本1.0接口");

    [MapToApiVersion("2.0")]
    [HttpGet]
    public IActionResult GetV2() => Ok("版本2.0接口");
}

路由模板中的v{version:apiVersion}必须和UrlSegmentApiVersionReader配合使用，才能让SwaggerUI自动填充版本号到URL中。

常见遗漏点总结 #

• 未开启ApiExplorerOptions.SubstituteApiVersionInUrl = true
• 未指定ApiVersionReader为UrlSegmentApiVersionReader（URL路径传版本场景）
• ConfigureSwaggerOptions未遍历IApiVersionDescriptionProvider生成全版本文档
• SwaggerUI的SwaggerEndpoint路径与版本分组名不匹配

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