乐趣区

如何使用Swagger为NET-Core-30应用添加JWT授权说明文档

jiezi

简介

本教程采用 WHY-WHAT-HOW 黄金圈思维模式编写，黄金圈法则强调的是从 WHY 为什么学，到 WHAT 学到什么，再到 HOW 如何学。从模糊到清晰的学习模式。大家的时间都很宝贵，我们做事前先想清楚为什么要做，学完能达到什么样的目标，然后我们再考虑要达到这个目的，通过什么样的方法来实现。

尝试一些事，遭遇失败后从中学习，比什么事都不做更好。—马克．佐克伯

为什么要学？

对于开发人员来说，调试 API 接口和生成 API 文档 是一件极其头疼的事情。我们在百忙之中，还不得不为前端开发人员编写接口文档，来描述系统中 N 个接口的参数及返回状态，再借助 PostMan 等第三方工具来测试 API 的正确性。在 Swagger 诞生后，这项体力活终于得到了极大的改善，我们不但可以自动构建漂亮的交互式 API 说明文档，还可以直接调试 API 接口的正确性。最新版的 Swagger 已经完美支持 Open Api 规范及 JWT Token 授权访问等。

能学到什么？

  • 使用 Swagger 生成精美的 API 接口文档
  • 使用 Swagger 调试 JWT 授权接口
  • 使用 Swagger 生成各个类库中视图模型的描述

怎么做？

Swagger 项目开源地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

创建一个.NET Core 项目

首先，新建一个.NET Core 3.0 Web Api 项目，打开 Nuget 安装管理器，勾选左下角的 显示预览发行包，搜索 Swashbuckle.AspNetCore，版本选择 5.0.0-rc4 的点添加，注意因为.NET Core 3.0 刚出不久，目前支持的库很多都是预览版，这里我选 5.0.0-beta 是会报错，选 5.0.0-rc4 使用正常。

设置生成 XML 描述信息

耐心等待几秒钟添加完成后，我们选中左侧刚才创建的 Api 项目，右键 > 属性（Mac 里叫选项），勾选 生成 XML 文档，这个是用来生成为 Swagger 所用的描述信息。

开始配置 Swagger

然后我们打开 Startup.cs 文件，来对 Swagger 配置进行一些必要的配置，在 ConfigureServices 方法我们添加一下 Swagger 配置：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Crypto Exchange",
        Description = "基于.NET Core 3.0 的区块链数字货币交易所",
        Contact = new OpenApiContact 
        {
            Name = "Microfisher",
            Email = "276679490@qq.com",
            Url = new Uri("http://cnblogs.com/microfisher"),
        },
    });

    // 加载程序集的 xml 描述文档
    var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
    var xmlFile = System.AppDomain.CurrentDomain.FriendlyName+ ".xml";
    var xmlPath = Path.Combine(baseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
})

参数都很简单，就是 Swagger 界面上显示的一些信息，注意这里一定要习惯使用 Path.Combine 来拼接路径，很多同学喜欢双斜杠来拼接，在 Mac 和 Linux 下是会出问题的，既然已经拥抱开源技术，尽量使用 Mac 或 Linux 来开发.NET Core 吧。然后我们在 Configure 方法里添加以下代码：

app.UseSwagger();
app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "Crypto Exchange");
    // 访问 Swagger 的路由后缀
    c.RoutePrefix = "swagger";
});

预览一下小成果

到这里为止，我们的 Swagger 的最基本的配置就完成了，其中 RoutePrefix 是访问 Swagger 的路由，如果设置为空则不需要输入 /swagger 后缀来访问。现在我们 F5 启动项目看看，我的本地网址是 https://localhost:5000，所以直接访问：https://localhost:5000/swagger 如下图所示，我去这界面也太丑了，说好的精美绝伦呢？不急不急，我们慢慢调优：

启用 API 文档的 JWT 授权

目前很多网站都使用了 JWT（JSON WEB TOKEN）来作为账户系统的认证授权，JWT 以它的简单、高效、分布式优势很快成为了网站的流行验证方式。这里我们不做过多的介绍，如果大家感兴趣我可以再写一篇长文来介绍 JWT 的优势和使用方法。我们继续来为 Swagger 添加 JWT 授权认证，依旧打开 Startup.cs 文件，修改上面 ConfigureServices 方法中的代码：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Crypto Exchange",
        Description = "基于.NET Core 3.0 的区块链数字货币交易所",
        Contact = new OpenApiContact
        {
            Name = "Microfisher",
            Email = "276679490@qq.com",
            Url = new Uri("http://cnblogs.com/microfisher"),
        },
    });

    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Description = "在下框中输入请求头中需要添加 Jwt 授权 Token：Bearer Token",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] {}
        }
    });

    var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
    var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml";
    var xmlPath = Path.Combine(baseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

预览一下授权设置

然后再启动项目，你会发现右侧多了一个 Authorize 绿色的带锁按钮，这个按钮点开后就可以设置我们的 JWT Token 信息了，格式是：Bearer 你的 Token 字符串，注意 Bearer 于 Token 之间有个空格。设置好 Token 后，你请求任意的 API 接口时，Swagger 会自动附带 Token 到请求的 Header 中。

创建一个 RESTFUL 接口

上面我们已经实现了 Swagger 的各项配置，现在我们来删除默认生成的控制器 WeatherForecastController 及视图模型WeatherForecast，新建一个 AccountController 及几个视图模型，让 Swagger 返回带描述的接口文档。

//[Authorize]
[Produces("application/json")]
[Route("v1/[controller]")]
[ApiController]
public class AccountController : ControllerBase
{
    /// <summary>
    /// 创建信息
    /// </summary>
    /// <param name="createViewModel"> 参数 </param>
    /// <returns> 状态 </returns>
    [HttpPost]
    public StatusViewModel Post([FromBody]CreateViewModel createViewModel)
    {return new StatusViewModel {};
    }

    /// <summary>
    /// 删除信息
    /// </summary>
    /// <param name="deleteViewModel"> 参数 </param>
    /// <returns></returns>
    [HttpDelete]
    public StatusViewModel Delete([FromQuery]DeleteViewModel deleteViewModel)
    {return new StatusViewModel {};
    }

    /// <summary>
    /// 查询信息
    /// </summary>
    /// <param name="queryViewModel"> 参数 </param>
    /// <returns></returns>
    [HttpGet]
    public StatusViewModel Get([FromQuery]QueryViewModel queryViewModel)
    {return new StatusViewModel {};
    }

    /// <summary>
    /// 修改信息
    /// </summary>
    /// <param name="updateViewModel"> 参数 </param>
    /// <returns></returns>
    [HttpPut]
    public StatusViewModel Put([FromQuery]UpdateViewModel updateViewModel)
    {return new StatusViewModel {};
    }
}

创建几个视图模型

再按自己喜欢的风格新建几个视图模型，用 /// 为各个字段添加 summary 后如下：

public class UpdateViewModel
{
    /// <summary>
    /// ID
    /// </summary>
    public long Id {get; set;}

    /// <summary>
    /// 账号
    /// </summary>
    public long Account {get; set;}

    /// <summary>
    /// 密码
    /// </summary>
    public long Password {get; set;}
}

测试最终成果

最后我们来看看效果，随便展开一个 API 接口，可以看到我们给视图模型写的注释已经显示在 Swagger 上了，前端开发人员一看就懂，输入一些接口参数，点一下执行就能看到返回值了：

再看我们的请求 Header 中已经包含了 JWT 授权信息（Bearer 123456789）是我随意设置的，让你们前端调试的时候换成你们的 Token 就行了。

项目代码，喜欢请加个星

https://github.com/microfisher/Tutorials
本篇文章由一文多发平台 ArtiPub 自动发布

退出移动版