.NET 8 API路由版本化：Swagger UI未显示完整v1.0版本串

DevOps 小满

2026-6-15

解决.NET 8 API路由版本化Swagger UI显示版本号简化问题

问题根源

Asp.Versioning默认会将ApiVersion(1, 0)这类版本号简化为1，而非完整的1.0，导致Swagger UI生成的路径显示为/v1/xxx，而非预期的/v1.0/xxx。

配置层面解决方案

无需自定义IDocumentFilter，只需在服务配置阶段调整ApiVersioning和ApiExplorer的版本格式设置：

1. 调整ApiVersioning的版本格式化规则

在Program.cs中配置AddApiVersioning时，指定版本的字符串格式，强制保留完整的主副版本号：

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    // 配置版本格式，V代表主版本号，v代表副版本号，格式为"V.v"
    options.ApiVersionFormatter = new ApiVersionFormatter
    {
        Format = "V.v"
    };
})

2. 同步ApiExplorer的分组格式

紧接着配置AddApiExplorer时，设置分组名称格式与上面保持一致，确保Swagger能正确读取完整版本号：

.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'V.v";
    options.SubstituteApiVersionInUrl = true;
});

3. 验证Swagger文档生成配置

确保SwaggerGen基于ApiExplorer的分组生成文档时，版本号使用完整格式：

builder.Services.AddSwaggerGen(options =>
{
    var apiVersionDescriptionProvider = builder.Services.BuildServiceProvider()
        .GetRequiredService<IApiVersionDescriptionProvider>();

    foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo
        {
            Title = "你的API名称",
            Version = description.ApiVersion.ToString()
        });
    }
});