如何使用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 = "[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";
});
預覽一下小成果
到這裡為止,我們的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 = "[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; }
}
測試最終成果
最後我們來看看效果,隨便展開一個API介面,可以看到我們給檢視模型寫的註釋已經顯示在Swagger上了,前端開發人員一看就懂,輸入一些介面引數,點一下執行就能看到返回值了:
再看我們的請求Header中已經包含了JWT授權資訊(Bearer 123456789)是我隨意設定的,讓你們前端除錯的時候換成你們的Token就行了。
專案程式碼,喜歡請加個星
https://github.com/microfisher/Tutorials