一、前言
结合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 实现的基础安全操作。具体细化操作，可阅读笔者其他内容。
