41.【.NET8 实战--孢子记账--从单体到微服务--转向微服务】--扩展功能--集成网关--网关集成Swagger

在这篇文章中讲解的网关集成Swagger的功能，主要是为了在网关层面上提供一个统一的API文档入口，方便再开发环境中前后端联调，在生产环境中是没有这个的。通过集成Swagger，我们可以在网关上直接访问所有微服务的API文档，而不需要单独访问每个微服务的Swagger UI。这种方式不仅提高了开发和测试的效率，还能让前端开发人员更方便地了解后端服务的接口。

要在网关项目中集成其他微服务的Swagger文档，我们首先要做的是在网关项目中安装MMLib.SwaggerForOcelot包，这个包可以帮助我们将Ocelot网关与Swagger集成起来。安装命令如下：

dotnet add package MMLib.SwaggerForOcelot

Tip：感谢开发MMLib.SwaggerForOcelot的大佬‘Miňo Martiniak’，GitHub地址：https://github.com/Burgyn/MMLib.SwaggerForOcelot

接下来，我们需要在网关的Program.cs文件中进行一些配置，以下是相关代码：

// more code...
if (builder.Environment.IsDevelopment() || builder.Environment.EnvironmentName == "Local")
{// Swagger 配置builder.Services.AddSwaggerGen();builder.Services.AddSwaggerForOcelot(builder.Configuration);
}// more code...// 中间件管道
if (app.Environment.IsDevelopment() || app.Environment.EnvironmentName == "Local")
{app.UseSwagger();app.UseSwaggerForOcelotUI(opt =>{opt.PathToSwaggerGenerator = "/swagger/docs";});
}// more code...

在上面代码中，我们首先检查当前环境是否为开发环境或本地环境，如果是，则添加Swagger生成器和Ocelot的Swagger支持。接着，在中间件管道中，我们使用UseSwagger()来启用Swagger文档生成，并使用UseSwaggerForOcelotUI()来配置Swagger UI的路径。

这些都配置完成后，我们就要在nacos中添加SwaggerConfig配置，具体内容如下：

{"SwaggerConfig": {"GatewayTitle": "SporeAccounting Gateway API","Version": "v1","Description": "统一API网关 - 集成所有微服务的Swagger文档","RoutePrefix": "swagger","EnabledServices": ["identity","config", "currency","finance","report"],"ServiceNameMapping": {"identity": "Identity Service","config": "Config Service","currency": "Currency Service","finance": "Finance Service","report": "Report Service"},"AliasToNacosServiceName": {"identity": "SPIdentityService","config": "SPConfigService","currency": "SPCurrencyService","finance": "SPFinanceService","report": "SPReportService"}},"SwaggerServices": [{"Name": "财务服务","ServiceName": "SPFinanceService","Description": "财务管理相关 API","IsActive": true},{"Name": "身份服务","ServiceName": "SPIdentityService","Description": "用户身份认证相关 API","IsActive": true},{"Name": "货币服务","ServiceName": "SPCurrencyService","Description": "货币管理相关 API","IsActive": true},{"Name": "配置服务","ServiceName": "SPConfigService","Description": "系统配置相关 API","IsActive": true},{"Name": "报表服务","ServiceName": "SPReportService","Description": "报表生成相关 API","IsActive": true}],"SwaggerEndPoints": [{"Key": "finance","Config": [{"Name": "Finance Service","Version": "v1","Url": "http://localhost:8977/finance/swagger/v1/swagger.json"}]},{"Key": "identity","Config": [{"Name": "Identity Service","Version": "v1","Url": "http://localhost:8977/identity/swagger/v1/swagger.json"}]},{"Key": "config","Config": [{"Name": "Config Service","Version": "v1","Url": "http://localhost:8977/config/swagger/v1/swagger.json"}]},{"Key": "currency","Config": [{"Name": "Currency Service","Version": "v1","Url": "http://localhost:8977/currency/swagger/v1/swagger.json"}]},{"Key": "report","Config": [{"Name": "Report Service","Version": "v1","Url": "http://localhost:8977/report/swagger/v1/swagger.json"}]}]
}

在这个配置中，我们定义了网关的基本信息，如标题、版本和描述等。同时，我们指定了需要集成Swagger文档的微服务名称，并为每个微服务提供了别名和Nacos服务名称的映射。

最后一步，我们要修改ocelot.json配置，在每个Route配置下增加SwaggerKey属性，这个属性的值就是我们在SwaggerConfig中定义的Key名称。以下是一个示例：

{"Routes": [{"DownstreamPathTemplate": "/{everything}","DownstreamScheme": "http","UpstreamPathTemplate": "/identity/{everything}","UpstreamHttpMethod": ["GET", "POST", "PUT", "DELETE", "PATCH"],"ServiceName": "SPIdentityService","UseServiceDiscovery": true,"LoadBalancerOptions": { "Type": "RoundRobin" },"SwaggerKey": "identity"  // 新增：匹配 SwaggerEndPoints 的 Key},// more configuration...],// more configuration...
}

增加SwaggerKey属性后，Ocelot网关就能根据这个键值来匹配对应的Swagger文档配置。
这样配置完成后，我们就可以在浏览器中访问http://localhost:8977/swagger/index.html来查看所有微服务的Swagger文档了。

Tip：注意，SwaggerConfig配置和SwaggerKey属性只可以出现在开发环境和本地环境中，生产环境中一定不能有这个配置。

总结

通过以上步骤，我们成功地在Ocelot网关中集成了Swagger文档，使得所有微服务的API文档可以通过统一的入口访问。这种方式不仅提高了开发效率，还能让前端开发人员更方便地了解后端服务的接口。
在实际开发中，在本地和开发环境中使用这种集成方式，而在生产环境中则不能集成Swagger，以减少不必要的性能开销和安全风险。