Ocelot之网关中统一配置Swagger
Ocelot之网关中统一配置Swagger
前言
上章节介绍了Ocelot之结合IdentityServer4认证二,在Ocelot网关中进行认证。在做微服务的时候,由于我们是采用前后端分离来开发的,提供给前端的直接是Swagger,如果Swagger分布在各个API中,前端查看Swagger的时候非常不便,因此,我们试着将Swagger集中放到网关中。
环境
Win10+VS2022 +.NET5.0 + Ocelot17.0.0.0 + Consul 1.6.1.1+IDS4
1 Swagger
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势:
- 支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
- 提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。
2 项目实现
项目结构如下:
运行结果:
在上节“Ocelot之结合IdentityServer4认证二”的项目实现上继续改造。
2.1 修改接口
1.添加Swashbuckle.AspNetCore依赖
添加后所有的依赖有:
<ItemGroup> <PackageReference Include="Consul" Version="1.6.1.1" /> <PackageReference Include="Microsoft.Extensions.PlatformAbstractions" Version="1.1.0" /> <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" /> </ItemGroup> |
2.修改Startup文件,添加Swagger代码
修改StartUp.cs文件的代码时,注意在使用中间件的时候,UseSwagger一定要在UseOcelot之前。
public void ConfigureServices(IServiceCollection services) { services.AddSwaggerGen(c => { c.SwaggerDoc("Yak.Ocelot.Api", new OpenApiInfo { Title = "天气预报服务", Version = "v1" }); c.DocInclusionPredicate((docName, description) => true); var baseDirectory = AppDomain.CurrentDomain.BaseDirectory; //此处为API的项目描述文件名 var commentsFileName = "Yak.Ocelot.Api.xml"; var commentsFile = Path.Combine(baseDirectory, commentsFileName); c.IncludeXmlComments(commentsFile); });
services.AddSingleton(Configuration.GetSection("Consul").Get<ConsulOption>()); services.AddControllers(); }
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IHostApplicationLifetime lifetime, ConsulOption consulOption) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } //启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(c => { c.RouteTemplate = "{documentName}/swagger.json"; }); //启用中间件服务对swagger-ui,指定Swagger JSON终结点/swagger/ app.UseSwaggerUI(c => c.SwaggerEndpoint("/Yak.Ocelot.Api/swagger.json", "Yak.Ocelot.Api v1")); // 注册 app.RegisterConsul(lifetime, consulOption); app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); } |
3.添加XML文档。
文件命名为“Yak.Ocelot.Api.xml”。
2.2 修改网关
1.添加Swashbuckle.AspNetCore依赖
添加后所有的依赖有:
<ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="5.0.0" /> <PackageReference Include="Ocelot" Version="17.0.0" /> <PackageReference Include="Ocelot.Cache.CacheManager" Version="17.0.0" /> <PackageReference Include="Ocelot.Provider.Consul" Version="17.0.0" /> <PackageReference Include="Ocelot.Provider.Polly" Version="17.0.0" /> <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" /> </ItemGroup> |
1. 修改ocelot配置
添加swagger配置。
{ "Routes": [ { "DownstreamPathTemplate": "/Yak.Ocelot.Api/swagger.json", "DownstreamScheme": "http", "ServiceName": "service-a", "LoadBalancer": "RoundRobin", "UseServiceDiscovery": true, "UpstreamPathTemplate": "/Yak.Ocelot.Api/swagger.json", "UpstreamHttpMethod": [ "GET", "POST", "DELETE", "PUT" ] }, { "DownstreamPathTemplate": "/WeatherForecast", "DownstreamScheme": "http", "ServiceName": "service-a", "UseServiceDiscovery": true, "UpstreamPathTemplate": "/Weather", "UpstreamHttpMethod": [ "Get" ], "LoadBalancerOptions": { "Type": "RoundRobin" }, //熔断器Polly "QoSOptions": { "ExceptionsAllowedBeforeBreaking": 3, //打开断路器之前允许的多少个异常请求 "DurationOfBreak": 60000, // 熔断时间 "TimeoutValue": 1000 //请求超时时间(毫秒) }, //鉴权 "AuthenticationOptions": { "AuthenticationProviderKey": "Gatewaykey", "AllowedScopes": [ "Yak.Ocelot.Api" ] } } ], "GlobalConfiguration": { "BaseUrl": "http://localhost:5000" } } |
2. 修改Startup文件,添加认证代码。
public void ConfigureServices(IServiceCollection services) { var identityBuilder = services.AddAuthentication(); IdentityServerConfig identityServerConfig = new IdentityServerConfig();
IdentityModelEventSource.ShowPII = true; var authenticationProviderKey = "Gatewaykey"; services.AddAuthentication().AddJwtBearer(authenticationProviderKey, x => { x.Authority = "http://localhost:8000"; x.RequireHttpsMetadata = false; x.TokenValidationParameters = new TokenValidationParameters { ValidateAudience = false }; }); services.AddControllers();
services.AddOcelot(Configuration).AddConsul().AddPolly();
// Swagger services.AddSwaggerGen(options => { options.SwaggerDoc($"{Configuration["Swagger:DocName"]}", new OpenApiInfo { Title = Configuration["Swagger:Title"], Version = Configuration["Swagger:Version"] }); }); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); }
app.UseRouting(); app.UseAuthentication();//先鉴权,没有鉴权,授权是没有意义的
app.UseAuthorization();//后授权 app.UseEndpoints(endpoints => { endpoints.MapGet("/", async context => { await context.Response.WriteAsync("我是Ocelot网关!"); }); }); var apis = new List<string> { "Yak.Ocelot.Api" }; app.UseSwagger(); app .UseSwaggerUI(options => { apis.ForEach(m => { options.SwaggerEndpoint($"/{m}/swagger.json", m); }); }); app.UseOcelot(); } |
2.3 启动Consul
这里是Win10系统,下载相应的Consul后,在文件夹下创建启动BAT文件用于启动Consul,双击启动。
2.4 服务发现
启动“Yak.Ocelot.Api”项目,查看到服务已经注册到Consul中。
2.5 调试
- 运行接口
运行网关项目“Yak.Ocelot.Api”,通过网关地址访问SwaggerUI。
地址:http://localhost:6000/Swagger/index.html
2. 运行网关
运行网关项目“Yak.Ocelot.Gateway”,通过网关地址访问SwaggerUI。
地址:http://localhost:5000/Swagger/index.html
3 总结
这节主要介绍了在Ocelot网关上访问SwaggerUI,除了在接口上配置Swagger,还需要在Ocelot上配置Swagger。
4 鸣谢
https://github.com/domaindrivendev/Swashbuckle.AspNetCore
https://www.cnblogs.com/focus-lei/p/9047410.html
https://www.cnblogs.com/wskxy/p/10123714.html
5 源码
https://github.com/yandaniugithub/NETCore
本文来自博客园,作者:{春光牛牛,yak},转载请注明原文链接:https://www.cnblogs.com/yakniu/p/16132248.html
欢迎各位大佬们评论指正
QQ讨论群:610129902