ASP.NET Core集成OpenAPI：能否通过单端点返回多服务器API文档？

ASP.NET Core 配合 Swashbuckle.AspNetCore 包（官方推荐的OpenAPI集成工具）完全支持返回多服务器的OpenAPI v3文档，以下分场景给出具体实现方式：

场景1：同一个API部署在多台服务器（单文档多服务器） #

如果你的API部署在生产、预发布、本地等多台服务器，只需在配置Swagger时直接添加多个服务器配置即可：

配置代码（.NET 6+ Program.cs） #

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// 添加API服务
builder.Services.AddControllers();

// 配置Swagger生成器
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "我的业务API", Version = "v1" });

    // 添加多服务器配置
    c.AddServer(new OpenApiServer
    {
        Url = "https://api.prod.example.com/v1",
        Description = "生产环境服务器"
    });
    c.AddServer(new OpenApiServer
    {
        Url = "https://api.staging.example.com/v1",
        Description = "预发布环境服务器"
    });
    c.AddServer(new OpenApiServer
    {
        Url = "http://localhost:5000/v1",
        Description = "本地开发服务器"
    });
});

var app = builder.Build();

// 启用Swagger中间件
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "我的业务API V1");
});

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

效果 #

生成的/swagger/v1/swagger.json中会包含servers数组，Swagger UI顶部会出现服务器选择下拉框，可直接切换不同服务器测试接口。

场景2：单个端点展示多个不同API的文档（多文档多服务器） #

如果需要通过单个Swagger UI端点展示多台独立Web服务器的API文档（比如用户服务、订单服务），可以配置多个Swagger文档，并给每个文档绑定对应服务器：

配置代码 #

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddSwaggerGen(c =>
{
    // 注册多个API文档
    c.SwaggerDoc("user-api", new OpenApiInfo { Title = "用户服务API", Version = "v1" });
    c.SwaggerDoc("order-api", new OpenApiInfo { Title = "订单服务API", Version = "v1" });

    // 自定义文档过滤器，给不同文档绑定对应服务器
    c.DocumentFilter<ServerBindingFilter>();
});

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    // 添加多个文档端点
    c.SwaggerEndpoint("/swagger/user-api/swagger.json", "用户服务API V1");
    c.SwaggerEndpoint("/swagger/order-api/swagger.json", "订单服务API V1");
});

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

// 自定义文档过滤器
public class ServerBindingFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Servers.Clear();
        // 根据文档标题绑定对应服务器
        if (swaggerDoc.Info.Title == "用户服务API")
        {
            swaggerDoc.Servers.Add(new OpenApiServer
            {
                Url = "https://user-api.example.com/v1",
                Description = "用户服务生产服务器"
            });
        }
        else if (swaggerDoc.Info.Title == "订单服务API")
        {
            swaggerDoc.Servers.Add(new OpenApiServer
            {
                Url = "https://order-api.example.com/v1",
                Description = "订单服务生产服务器"
            });
        }
    }
}

效果 #

Swagger UI顶部会出现文档选择下拉框，切换不同文档时会自动加载对应服务器的API定义。

场景3：合并多服务器API文档为单个JSON返回 #

如果需要将多台服务器的API文档合并成一个swagger.json通过单个端点返回，需要自定义端点手动合并文档结构（需处理命名冲突，比如同名Schema）：

示例代码 #

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// 添加HttpClient用于获取其他API的文档
builder.Services.AddHttpClient();

builder.Services.AddControllers();

var app = builder.Build();

// 自定义合并文档端点
app.MapGet("/combined-swagger", async (HttpClient client) =>
{
    // 获取各服务器的OpenAPI文档
    var userApiDoc = await client.GetFromJsonAsync<OpenApiDocument>("https://user-api.example.com/swagger/v1/swagger.json");
    var orderApiDoc = await client.GetFromJsonAsync<OpenApiDocument>("https://order-api.example.com/swagger/v1/swagger.json");

    if (userApiDoc == null || orderApiDoc == null)
    {
        return Results.BadRequest("无法获取API文档");
    }

    // 合并文档结构
    var combinedDoc = new OpenApiDocument
    {
        Info = new OpenApiInfo { Title = "合并API文档", Version = "v1" },
        // 合并服务器列表
        Servers = userApiDoc.Servers.Concat(orderApiDoc.Servers).ToList(),
        // 合并接口路径
        Paths = userApiDoc.Paths.Concat(orderApiDoc.Paths).ToDictionary(kv => kv.Key, kv => kv.Value),
        // 合并组件（需处理命名冲突，这里简单合并，实际需添加前缀或重命名）
        Components = new OpenApiComponents
        {
            Schemas = userApiDoc.Components.Schemas.Concat(orderApiDoc.Components.Schemas).ToDictionary(kv => kv.Key, kv => kv.Value),
            Parameters = userApiDoc.Components.Parameters.Concat(orderApiDoc.Components.Parameters).ToDictionary(kv => kv.Key, kv => kv.Value)
        }
    };

    return Results.Json(combinedDoc, new System.Text.Json.JsonSerializerOptions { WriteIndented = true });
});

app.UseHttpsRedirection();
app.Run();

注意事项 #

合并文档时需注意处理命名冲突（如两个API有同名的Schema、参数），可通过给冲突项添加前缀或重命名解决。

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