Asp.Net Core遇到Swagger(五)-Swashbuckle-Jwt篇

一、前言

结合Asp.Net Core认证-Jwt-基础篇，本篇文章将讲解基于Swashbuckle的实践应用操作和配置。Swashbuckle 基于 Jwt 实现安全认证。

二、实践技巧

使用 Swagger 添加 Jwt 安全认证的前提是，当前项目已经引入 Jwt 验证，实现基本的 Jwt 生成和认证功能。此处将不再重复讲解，具体可参考[Asp.Net Core认证-Jwt-基础篇]https://blog.csdn.net/qq_28806349/article/details/120191348，以下为 基础篇 中引入Swashbuckle相关类库时，需要的如下操作。

2.1、引入依赖

Nuget引入库依赖，项目中依赖版本如下：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="3.1.17" />
    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="6.0.0" />
    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.0.0" />
  </ItemGroup>

</Project>

2.2、配置服务

Startup.cs中添加服务与启用对应中间件，代码如下：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    //设置secret
    byte[] secret = System.Text.Encoding.UTF8.GetBytes("1234567890123456");
    //添加认证服务
    services.AddAuthentication(config => {
        //设置默认架构
        config.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
        //默认认证架构
        //config.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    
    //添加Jwt自定义配置
    .AddJwtBearer(config => {
                //设置Token验证参数项
                config.TokenValidationParameters = new TokenValidationParameters
                {
                    //认证秘钥
                    IssuerSigningKey = new SymmetricSecurityKey(secret),
                    //是否调用对 securityToken 签名的
                    //Microsoft.IdentityModel.Tokens.SecurityKey 的验证
                    ValidateIssuerSigningKey = true,

                    //颁发者
                    ValidIssuer = "ggcy",
                    //是否验证颁发者
                    ValidateIssuer = true,

                    //受众
                    ValidAudience = "Audience",
                    //是否验证受众
                    ValidateAudience = true,

                    //是否验证凭证有效时限
                    ValidateLifetime = true,
                    ClockSkew = TimeSpan.FromMinutes(5)
                };
            });

    services.AddSwaggerGen(options => {
        #region Jwt
        //定义安全方案
        options.AddSecurityDefinition("oauth2", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
        {
            //描述信息
            Description = "请输入带有Bearer的Token，形如 “Bearer {Token}” ",
            //Header对应名称
            Name = "Authorization",
            //验证类型，此处使用Api Key
            Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
            //设置 API 密钥的位置
            In = Microsoft.OpenApi.Models.ParameterLocation.Header
        });
        //指定方案应用范围
        options.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement {
                {
                    new Microsoft.OpenApi.Models.OpenApiSecurityScheme {
                     Reference = new Microsoft.OpenApi.Models.OpenApiReference
                     { Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,Id="oauth2"}
                    },
                    new []{
                    "readAccess",
                    "writeAccess"
                    } 
                }
            });
        #endregion
    });
}

2.3、启用中间件

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    // 1、启用静态文件中间件
    app.UseStaticFiles();

    // 2、添加Swagger中间件到管道中
    app.UseSwagger();

    // 3、添加SwaggerUI到管道中
    app.UseSwaggerUI();
    
    app.UseRouting();
    //启用认证管道中间件
    app.UseAuthentication();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

需要注意的是，由于SwaggerUI需要请求服务端的静态资源，所以需要在启用SwaggerUI中间件前，开启静态资源中间件，建议测试使用时，依据注释部分进行中间件引入。

2.4、测试认证

配置完成后，调试运行，访问默认地址 http://localhost:5000/swagger/index.html ，出现如下结果：

1）获取Token

请求文档中的 Token 接口，获取到认证的之后的 Token 值，操作如下：

2）请求接口

再次请求，能够依靠 Token ，通过认证，访问到对应 Api 数据。

以上为引入Jwt，再结合 Swashbuckle 实现的基础安全操作。具体细化操作，可阅读笔者其他内容。