如何在.NET Core WebAPI的Swagger中自定义版本号显示？

要让Swagger右上角的「选择定义」下拉框显示实际版本号而非默认模板内容，只需在配置Swagger服务和UI时显式指定版本的显示名称即可，具体步骤如下：

1. 配置Swagger文档元数据 #

在Program.cs（.NET 6+）或Startup.cs的ConfigureServices方法中，为每个API版本的Swagger文档设置清晰的显示名称：

builder.Services.AddSwaggerGen(c =>
{
    // 配置v1版本
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "我的WebAPI",
        Version = "v1",
        DisplayName = "API 版本 v1" // 自定义下拉框显示文本
    });

    // 配置v2版本
    c.SwaggerDoc("v2", new OpenApiInfo
    {
        Title = "我的WebAPI",
        Version = "v2",
        DisplayName = "API 版本 v2" // 自定义下拉框显示文本
    });

    // 可选：添加XML注释支持（按需配置）
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
    c.IncludeXmlComments(xmlFilePath);
});

2. 配置Swagger UI端点 #

在配置Swagger UI中间件时，为每个版本的端点指定对应的显示名称，这会直接映射到下拉框的选项文本：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API 版本 v1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "API 版本 v2");

    // 可选：UI个性化配置（比如默认隐藏模型）
    c.DefaultModelsExpandDepth(-1);
});

关键说明 #

• Swagger UI的下拉框选项文本优先读取SwaggerEndpoint方法的第二个参数，也会同步使用SwaggerDoc中设置的DisplayName，两者保持一致即可。
• 如果之前使用了默认模板（如{DocumentName}），只需替换为明确的版本标识文本即可覆盖默认显示。

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