本教程採用WHY-WHAT-HOW黃金圈思惟模式編寫,黃金圈法則強調的是從WHY爲何學,到WHAT學到什麼,再到HOW如何學。從模糊到清晰的學習模式。你們的時間都很寶貴,咱們作事前先想清楚爲何要作,學完能達到什麼樣的目標,而後咱們再考慮要達到這個目的,經過什麼樣的方法來實現。前端
嘗試一些事,遭遇失敗後從中學習,比什麼事都不作更好。—馬克.佐克伯git
對於開發人員來講,**調試API接口和生成API文檔是一件極其頭疼的事情。咱們在百忙之中,還不得不爲前端開發人員編寫接口文檔,來描述系統中N個接口的參數及返回狀態,再借助PostMan等第三方工具來測試API的正確性。在Swagger誕生後,這項體力活終於獲得了極大的改善,咱們不但能夠自動構建漂亮的交互式API說明文檔,還能夠直接調試API接口的正確性。最新版的Swagger已經完美支持Open Api規範及JWT Token受權訪問等。github
Swagger項目開源地址:github.com/domaindrive…json
首先,新建一個.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使用正常。bash
耐心等待幾秒鐘添加完成後,咱們選中左側剛纔建立的Api項目,右鍵>屬性(Mac裏叫選項),勾選***生成XML文檔***,這個是用來生成爲Swagger所用的描述信息。app
而後咱們打開***Startup.cs***文件,來對Swagger配置進行一些必要的配置,在***ConfigureServices***方法咱們添加一下Swagger配置:dom
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以下圖所示,我去這界面也太醜了,說好的精美絕倫呢?不急不急,咱們慢慢調優:工具
目前不少網站都使用了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中。
上面咱們已經實現了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就好了。