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 的优势：

1. 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
2. 提供 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 调试

1. 运行接口

运行网关项目“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