如何使用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項目開源地址： 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自動發佈