如何在 swagger UI 界面使用 JWT

1. 介绍

Swagger 是用于描述和记录 RESTful API 的开放规范，它是用于定义、生成、使用和可视化 RESTful Web 服务的标准规范和工具集。它使设计、构建、记录和高效使用 API 变得简单。

而 JWT 即 JSON Web Tokens 的简称，是一项拟议的互联网标准，用于创建具有可选签名和/或可选加密的数据，其有效负载包含声明一定数量声明的 JSON。令牌使用私钥或公钥/私钥进行签名。

如果我们在 API 项目中使用了 JWT， 这时你会发现并不能直接在 Swagger 的界面中直接获取到数据，因为这时获取数据都必须要一个JWT的令牌，那么我们如何在此环境中使用JWT呢？ OK，我将在这篇文章中为你介绍如何使用它！

2. 配置 Swagger

首先我们在 Program.cs 里对 Swagger 做一些相应的配置，在以下方法里，将 Swagger 添加到系统服务中

builder.Services.AddSwaggerGen(options =>
{
    //...
}

接下来，如果我们想在 WEB 界面中支持 JWT， 就要添加以下代码

builder.Services.AddSwaggerGen(options =>
{
     // 添加 JWT 验证支持
    var securityScheme = new OpenApiSecurityScheme
    {
        Name = "JWT Authentication",
        Description = "Enter JWT Bearer token **_only_**",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.Http,
        Scheme = "bearer", // 一定要小写
        BearerFormat = "JWT",
        Reference = new OpenApiReference
        {
            Id = JwtBearerDefaults.AuthenticationScheme,
            Type = ReferenceType.SecurityScheme
        }
    };
    options.AddSecurityDefinition(securityScheme.Reference.Id, securityScheme);
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {securityScheme, new string[] { }}
    });
});

顺便一提的是，你还可以改变默认的 Swagger 文档相关描述

options.SwaggerDoc("v1", new OpenApiInfo
{
    Version = "v1",
    Title = "MyDemo API",
    Description = "My Demo API by Winson from CoderBlog.cc",
    TermsOfService = new Uri("https://www.coderblog.cc"),
    Contact = new OpenApiContact
    {
        Name = "Contact",
        Url = new Uri("https://www.coderblog.cc")
    },
    License = new OpenApiLicense
    {
        Name = "Example License",
        Url = new Uri("https://example.com/license")
    }
});

3. 找到 JWT 并使用

配置完后，重启 API 网站，然后你会发现多了一个 Authorize 的按钮在 Swagger 的界面中

当按下此按钮后，就会弹出一个让你输入 JWT 的对话框

这时你就会问，我要如何找到这个 JWT 令牌呢？ 好的，你可以登录到使用此 API 开发的网站（我使用的是之前写的一个 demo 网站），当你使用 Chrome 登录后，就可以通过以下控制台在 Application 里找到你的 JWT 令牌了

这时只需在 Swagger 的界面中输入找到的 JWT 值，就会看到说是登录成功的状态

之后就会发现所有 API 都变成锁上状态，代表已成功登录了

现在你就可以尝试访问你的 API 了! 🙂

同时如果你修改了 Swagger 文档信息，将会发现这时界面上也会产生了相应的改变

4. 总结

Swagger 对于测试 API 和查找 bug 很有帮助，但是如果我们使用 JWT 令牌则需要做如上的设置让 Swagger 支持它，这样可以为我们节省很多测试 API 的时间哦~

相关文章：

使用 VS CODE 建立你的第一个 ASP.NET Core API 项目 如何配置开发 ASP.NET Core 项目的 VS Code 环境 如何在 .Net Core 里创建和使用中间件