如何使用Swagger为.NET Core 3.0应用添加JWT受权说明文档

简介

本教程采用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项目开源地址：github.com/domaindrive…

建立一个.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就好了。

项目代码，喜欢请加个星

github.com/microfisher…