如何将所有C#微服务聚合到同一Swagger页面（基于Ocelot网关）

1. 先给每个微服务配置独立Swagger #

每个微服务的Program.cs里要先搭好Swagger基础配置，确保自身能生成Swagger文档，同时允许网关访问：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "ServiceA API", Version = "v1" });
    // 要是有JWT这类认证，这里得同步配置安全规则，不然聚合后接口权限显示会有问题
});

// 中间件部分
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ServiceA API v1");
});

// 加跨域配置，避免网关拉取文档时跨域报错
app.UseCors(builder => builder.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader());

其他两个微服务照这个逻辑抄，改下标题就行。

2. 网关端配置Swagger聚合 #

网关项目先装两个包：Swashbuckle.AspNetCore和Ocelot.Provider.Swagger，注意版本要和你的.NET版本匹配。

2.1 配置服务注入 #

在网关的Program.cs里加这些代码：

builder.Services.AddOcelot();
builder.Services.AddSwaggerForOcelot(builder.Configuration); // 关键：添加Ocelot的Swagger聚合支持

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "聚合API网关", Version = "v1" });
});

2.2 修改Ocelot路由配置（ocelot.json） #

要给每个微服务加两类路由：业务接口路由、Swagger文档路由，还要配置聚合的Swagger端点：

{
  "Routes": [
    // ServiceA的业务接口路由
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{"Host": "servicea", "Port": 5001}],
      "UpstreamPathTemplate": "/servicea/{everything}",
      "UpstreamHttpMethod": ["Get", "Post", "Put", "Delete"],
      "SwaggerKey": "ServiceA"
    },
    // ServiceA的Swagger文档路由
    {
      "DownstreamPathTemplate": "/swagger/v1/swagger.json",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{"Host": "servicea", "Port": 5001}],
      "UpstreamPathTemplate": "/swagger/servicea/swagger.json",
      "UpstreamHttpMethod": ["Get"],
      "SwaggerKey": "ServiceA"
    },
    // 剩下两个微服务的路由照着上面的格式复制修改就行
  ],
  "SwaggerEndPoints": [
    {
      "Key": "ServiceA",
      "Config": [{"Name": "ServiceA业务接口", "Version": "v1", "Url": "/swagger/servicea/swagger.json"}]
    },
    // 另外两个微服务的SwaggerEndPoints配置同样复制修改
  ]
}

2.3 配置网关中间件 #

在网关的Program.cs里把中间件按顺序加上：

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "聚合API网关 v1");
});

app.UseOcelot().Wait();
// 关键：启用Ocelot的Swagger聚合UI
app.UseSwaggerForOcelotUI(c =>
{
    c.PathToSwaggerGenerator = "/swagger/docs";
});

3. 调试排查要点 #

• 先单独启动每个微服务，确认各自的Swagger能正常访问（比如http://localhost:5001/swagger）
• 启动网关后，访问网关的Swagger地址（默认http://localhost:5000/swagger），就能看到所有微服务的接口聚合在一个页面里
• 如果某个微服务的接口没显示，检查：
  • ocelot.json里的DownstreamHostAndPorts是不是填对了微服务的地址和端口
  • 微服务的跨域配置有没有生效
  • Swagger文档路由的UpstreamPathTemplate和SwaggerEndPoints里的Url是否一致

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