.NET 6 C# ASP.NET项目如何在Swagger JSON文件中添加host变量

下面是两种实用的配置方式，帮你在生成的Swagger JSON中指定客户端连接的Host地址：

1. 代码硬编码Host（快速测试场景） #

打开项目的Program.cs，找到Swagger配置代码块，通过自定义IDocumentFilter设置Host信息：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    
    // 注册自定义Host过滤器
    c.DocumentFilter<HostConfigFilter>();
});

// 自定义过滤器类，配置目标Host
public class HostConfigFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 替换为实际服务器地址，可添加多环境Host
        swaggerDoc.Servers = new List<OpenApiServer>
        {
            new OpenApiServer { Url = "https://prod.your-api.com" },
            new OpenApiServer { Url = "http://localhost:5000" }
        };
    }
}

2. 配置文件读取Host（多环境适配推荐） #

这种方式支持不同环境（开发/测试/生产）使用不同Host，灵活性更高：

第一步：添加配置项 #

在appsettings.json（对应环境的配置文件如appsettings.Production.json可单独覆盖配置）中添加Swagger Host设置：

"SwaggerHostSettings": {
  "ServerUrls": [
    "https://prod.your-api.com",
    "http://test.your-api.com"
  ]
}

第二步：创建配置映射类 #

public class SwaggerHostSettings
{
    public List<string> ServerUrls { get; set; } = new List<string>();
}

第三步：绑定配置并应用到Swagger #

回到Program.cs，修改Swagger配置代码：

// 绑定配置文件中的Host设置
builder.Services.Configure<SwaggerHostSettings>(builder.Configuration.GetSection("SwaggerHostSettings"));

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    
    // 读取配置并应用到Swagger文档
    var hostSettings = builder.Configuration.GetSection("SwaggerHostSettings").Get<SwaggerHostSettings>();
    c.DocumentFilter<ConfigurableHostFilter>(hostSettings);
});

public class ConfigurableHostFilter : IDocumentFilter
{
    private readonly SwaggerHostSettings _hostSettings;

    public ConfigurableHostFilter(SwaggerHostSettings hostSettings)
    {
        _hostSettings = hostSettings;
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Servers = _hostSettings.ServerUrls
            .Select(url => new OpenApiServer { Url = url })
            .ToList();
    }
}

验证配置效果 #

启动项目后，访问Swagger JSON地址（默认路径为/swagger/v1/swagger.json），查看返回内容中的servers节点，确认已包含你指定的Host地址。客户端生成工具（如NSwag、OpenAPI Generator）会自动读取该节点确定服务器连接地址。

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