簡介

隨著微軟.NET Core的誕生，除了恐龍以外第二個應該滅絕的.NET程式員，總算看到了一米陽光，真是做噩夢都沒想到，有一天我們也可以拋棄Windows這2貨，去擁抱主流的Linux+Docker的時代，

嘗試一些事，遭遇失敗后從中學習，比什么事都不做更好，—馬克．佐克伯

Swagger對我們有什么幫助？

對于開發人員來說，除錯API介面和生成API檔案是一件極其頭疼的事情，我們在百忙之中，不得不為前端開發人員撰寫介面檔案，來描述系統中N個介面的引數及回傳狀態，再借助PostMan等第三方工具來測驗API的正確性，

在有了Swagger后，這項體力活終于得到了極大的改善，我們不但可以自動構建漂亮的互動式API說明檔案，還可以直接除錯API介面的正確性，最新版的Swagger已經完美支持Open Api規范及JWT Token授權訪問等，

我們可以用它來做什么？

生成精美的API介面檔案
除錯JWT授權介面
生成各個類別庫中視圖模型的描述

專案開源地址

Swagger專案開源地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

1.創建一個.NET Core專案

首先，新建一個.NET Core 3.x Web Api 專案，打開Nuget安裝管理器，勾選左下角的顯示預覽發行包，搜索Swashbuckle.AspNetCore，版本選擇5.0.0-rc4的點添加，注意因為.NET Core 3.x剛出不久，目前支持的庫很多都是預覽版，這里我選5.0.0-beta是會報錯，選5.0.0-rc4使用正常，

創建專案

設定生成XML描述資訊

耐心等待幾秒鐘添加完成后，我們選中左側剛才創建的Api專案，右鍵>屬性（Mac里叫選項），勾選生成XML檔案，這個是用來生成為Swagger所用的描述資訊，

創建專案

開始配置Swagger

然后我們打開Startup.cs檔案，來對Swagger配置進行一些必要的配置，在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 = "[email protected]",
            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";
});

預覽一下小成果

到這里為止，最基本的配置就完成了，其中RoutePrefix是訪問Swagger的路由，如果設定為空則不需要輸入/swagger后綴來訪問，現在我們F5啟動專案看看，我的本地網址是https://localhost:5000，所以直接訪問：https://localhost:5000/swagger如下圖所示，我去這界面也太丑了，說好的精美絕倫呢？不急不急，我們慢慢調優

創建專案

啟用JWT授權

目前很多網站都使用了JWT（JSON WEB TOKEN）來作為賬戶系統的認證授權，JWT以它的簡單、高效、分布式優勢很快成為各大網站及APP的流行驗證方式，這里我們不做過多的介紹，如果大家感興趣我可以再寫一篇長文來介紹的優勢和使用方法，我們繼續來為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 = "[email protected]",
            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; }
}