簡介
本教程采用WHY-WHAT-HOW黃金圈思維模式編寫基跑，黃金圈法則強(qiáng)調(diào)的是從WHY為什么學(xué)橡淆，到WHAT學(xué)到什么棋枕，再到HOW如何學(xué)。從模糊到清晰的學(xué)習(xí)模式逸爵。大家的時(shí)間都很寶貴幅疼，我們做事前先想清楚為什么要做，學(xué)完能達(dá)到什么樣的目標(biāo)堂飞，然后我們再考慮要達(dá)到這個(gè)目的灌旧，通過什么樣的方法來實(shí)現(xiàn)绑咱。
嘗試一些事，遭遇失敗后從中學(xué)習(xí)枢泰，比什么事都不做更好描融。—馬克．佐克伯
為什么要學(xué)衡蚂？
對于開發(fā)人員來說窿克，調(diào)試API接口和生成API文檔是一件極其頭疼的事情。我們在百忙之中讳窟，還不得不為前端開發(fā)人員編寫接口文檔让歼，來描述系統(tǒng)中N個(gè)接口的參數(shù)及返回狀態(tài)，再借助PostMan等第三方工具來測試API的正確性丽啡。在Swagger誕生后谋右，這項(xiàng)體力活終于得到了極大的改善，我們不但可以自動構(gòu)建漂亮的交互式API說明文檔补箍，還可以直接調(diào)試API接口的正確性改执。最新版的Swagger已經(jīng)完美支持Open Api規(guī)范及JWT Token授權(quán)訪問等。
能學(xué)到什么坑雅？
- 使用 Swagger 生成精美的API接口文檔
- 使用 Swagger 調(diào)試JWT授權(quán)接口
- 使用 Swagger 生成各個(gè)類庫中視圖模型的描述
怎么做辈挂？
Swagger項(xiàng)目開源地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
創(chuàng)建一個(gè).NET Core項(xiàng)目
首先，新建一個(gè).NET Core 3.0 Web Api 項(xiàng)目裹粤，打開Nuget安裝管理器终蒂，勾選左下角的顯示預(yù)覽發(fā)行包，搜索Swashbuckle.AspNetCore遥诉，版本選擇5.0.0-rc4的點(diǎn)添加拇泣，注意因?yàn)?NET Core 3.0剛出不久，目前支持的庫很多都是預(yù)覽版矮锈，這里我選5.0.0-beta是會報(bào)錯(cuò)霉翔，選5.0.0-rc4使用正常。
設(shè)置生成XML描述信息
耐心等待幾秒鐘添加完成后苞笨，我們選中左側(cè)剛才創(chuàng)建的Api項(xiàng)目债朵，右鍵>屬性（Mac里叫選項(xiàng)），勾選生成XML文檔瀑凝，這個(gè)是用來生成為Swagger所用的描述信息序芦。
開始配置Swagger
然后我們打開Startup.cs文件，來對Swagger配置進(jìn)行一些必要的配置粤咪，在ConfigureServices方法我們添加一下Swagger配置：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Crypto Exchange",
Description = "基于.NET Core 3.0 的區(qū)塊鏈數(shù)字貨幣交易所",
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);
})
參數(shù)都很簡單谚中，就是Swagger界面上顯示的一些信息，注意這里一定要習(xí)慣使用Path.Combine來拼接路徑，很多同學(xué)喜歡雙斜杠來拼接藏杖，在Mac和Linux下是會出問題的将塑，既然已經(jīng)擁抱開源技術(shù)，盡量使用Mac或Linux來開發(fā).NET Core吧蝌麸。然后我們在Configure方法里添加以下代碼：
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Crypto Exchange");
// 訪問Swagger的路由后綴
c.RoutePrefix = "swagger";
});
預(yù)覽一下小成果
到這里為止点寥，我們的Swagger的最基本的配置就完成了，其中RoutePrefix是訪問Swagger的路由来吩，如果設(shè)置為空則不需要輸入/swagger后綴來訪問「冶纾現(xiàn)在我們F5啟動項(xiàng)目看看，我的本地網(wǎng)址是https://localhost:5000弟疆，所以直接訪問：https://localhost:5000/swagger如下圖所示戚长，我去這界面也太丑了，說好的精美絕倫呢怠苔？不急不急同廉，我們慢慢調(diào)優(yōu)：
啟用API文檔的JWT授權(quán)
目前很多網(wǎng)站都使用了JWT（JSON WEB TOKEN）來作為賬戶系統(tǒng)的認(rèn)證授權(quán)，JWT以它的簡單柑司、高效迫肖、分布式優(yōu)勢很快成為了網(wǎng)站的流行驗(yàn)證方式。這里我們不做過多的介紹攒驰，如果大家感興趣我可以再寫一篇長文來介紹JWT的優(yōu)勢和使用方法蟆湖。我們繼續(xù)來為Swagger添加JWT授權(quán)認(rèn)證，依舊打開Startup.cs文件玻粪，修改上面ConfigureServices方法中的代碼：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Crypto Exchange",
Description = "基于.NET Core 3.0 的區(qū)塊鏈數(shù)字貨幣交易所",
Contact = new OpenApiContact
{
Name = "Microfisher",
Email = "276679490@qq.com",
Url = new Uri("http://cnblogs.com/microfisher"),
},
});
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
{
Description = "在下框中輸入請求頭中需要添加Jwt授權(quán)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);
});
預(yù)覽一下授權(quán)設(shè)置
然后再啟動項(xiàng)目隅津，你會發(fā)現(xiàn)右側(cè)多了一個(gè)Authorize綠色的帶鎖按鈕，這個(gè)按鈕點(diǎn)開后就可以設(shè)置我們的JWT Token信息了劲室，格式是：Bearer 你的Token字符串伦仍，注意Bearer于Token之間有個(gè)空格。設(shè)置好Token后痹籍，你請求任意的API接口時(shí)呢铆，Swagger會自動附帶Token到請求的Header中晦鞋。
創(chuàng)建一個(gè)RESTFUL接口
上面我們已經(jīng)實(shí)現(xiàn)了Swagger的各項(xiàng)配置蹲缠，現(xiàn)在我們來刪除默認(rèn)生成的控制器WeatherForecastController及視圖模型WeatherForecast，新建一個(gè)AccountController及幾個(gè)視圖模型悠垛，讓Swagger返回帶描述的接口文檔线定。
//[Authorize]
[Produces("application/json")]
[Route("v1/[controller]")]
[ApiController]
public class AccountController : ControllerBase
{
/// <summary>
/// 創(chuàng)建信息
/// </summary>
/// <param name="createViewModel">參數(shù)</param>
/// <returns>狀態(tài)</returns>
[HttpPost]
public StatusViewModel Post([FromBody]CreateViewModel createViewModel)
{
return new StatusViewModel { };
}
/// <summary>
/// 刪除信息
/// </summary>
/// <param name="deleteViewModel">參數(shù)</param>
/// <returns></returns>
[HttpDelete]
public StatusViewModel Delete([FromQuery]DeleteViewModel deleteViewModel)
{
return new StatusViewModel { };
}
/// <summary>
/// 查詢信息
/// </summary>
/// <param name="queryViewModel">參數(shù)</param>
/// <returns></returns>
[HttpGet]
public StatusViewModel Get([FromQuery]QueryViewModel queryViewModel)
{
return new StatusViewModel { };
}
/// <summary>
/// 修改信息
/// </summary>
/// <param name="updateViewModel">參數(shù)</param>
/// <returns></returns>
[HttpPut]
public StatusViewModel Put([FromQuery]UpdateViewModel updateViewModel)
{
return new StatusViewModel { };
}
}
創(chuàng)建幾個(gè)視圖模型
再按自己喜歡的風(fēng)格新建幾個(gè)視圖模型，用///為各個(gè)字段添加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; }
}
測試最終成果
最后我們來看看效果确买，隨便展開一個(gè)API接口斤讥，可以看到我們給視圖模型寫的注釋已經(jīng)顯示在Swagger上了，前端開發(fā)人員一看就懂，輸入一些接口參數(shù)芭商，點(diǎn)一下執(zhí)行就能看到返回值了：
再看我們的請求Header中已經(jīng)包含了JWT授權(quán)信息（Bearer 123456789）是我隨意設(shè)置的派草，讓你們前端調(diào)試的時(shí)候換成你們的Token就行了。
