一、Swagger簡(jiǎn)介
1.1-什么是Swagger?
- Swagger是一個(gè)規(guī)范且完整的框架，用于生成、描述、調(diào)試和可視化Restfull風(fēng)格的Web服務(wù)。
- Swagger的目標(biāo)是對(duì)Rest API定義一個(gè)標(biāo)準(zhǔn)且和語(yǔ)言無(wú)關(guān)的接口，可以讓人和計(jì)算機(jī)擁有無(wú)需訪問(wèn)源碼、文檔或網(wǎng)絡(luò)流量監(jiān)控就可以發(fā)現(xiàn)和連接服務(wù)的能力。當(dāng)通過(guò)Swagger進(jìn)行正確定義，用于可以理解遠(yuǎn)程服務(wù)并使用最少邏輯與遠(yuǎn)程服務(wù)進(jìn)行交互。與為底層編程所實(shí)現(xiàn)的接口類(lèi)似，Swagger消除了調(diào)用服務(wù)時(shí)可能會(huì)有的猜測(cè)。
1.2-Swagger有什么優(yōu)勢(shì)？
- 支持API自動(dòng)生成同步的在線文檔：使用Swagger后可以直接通過(guò)代碼生成文檔，不需要自己去手動(dòng)編寫(xiě)接口文檔了，對(duì)程序員來(lái)說(shuō)是非常方便。
- 提供Web頁(yè)面在線測(cè)試API：光有文檔還不夠，Swagger生成的文檔還支持在線測(cè)試。參數(shù)和格式都一定定義好了，直接在界面上輸出參數(shù)對(duì)應(yīng)的值即可在先測(cè)試接口。
- Swagger可以生成客戶端SDK代碼用于各種不同平臺(tái)的實(shí)現(xiàn)。
- Swagger文件可以在許多不同的平臺(tái)上從代碼注釋中自動(dòng)生成。
- Swagger有一個(gè)強(qiáng)大的社區(qū)，里面有許多強(qiáng)悍的貢獻(xiàn)者。
1.3-Swagger、OpenAPI3.0、Restful API的區(qū)別？
- Open API：OpenAPI是規(guī)范的正式名稱(chēng)。該規(guī)范的開(kāi)發(fā)時(shí)由OpenAPI Initative推動(dòng)的。該提倡涉及不同領(lǐng)域的30個(gè)組織——包括Microsoft、Google、IBM和CapitalOne.
- Swagger：實(shí)現(xiàn)OpenAPI規(guī)范的工具之一。
- RestfulAPI：是一種WebAPI設(shè)計(jì)架構(gòu)風(fēng)格。其中Rest即Represntaional State Transfer的縮寫(xiě)，可以翻譯為"狀態(tài)表述轉(zhuǎn)換"。是目前比較成熟的一套互聯(lián)網(wǎng)應(yīng)用程序的API設(shè)計(jì)架構(gòu)風(fēng)格OpenAPI規(guī)范即是這個(gè)架構(gòu)風(fēng)格的具體實(shí)現(xiàn)規(guī)范。
1.4-Swagger工具
1.5-Swagger UI工具主要功能
- 接口的文檔在線自動(dòng)生成
- 功能測(cè)試等
1.6-Swashbuckle組件
- Swashbuckle是.NET Core中對(duì)Swagger的封裝，他有2個(gè)核心組件：
- Swashbuckle.SwaggerGen：提供生成對(duì)象、方法、返回類(lèi)型等JSON Swagger文檔的功能。
- Swashbuckle.SwaggerUI：是一個(gè)嵌入式版本的SwaggerUI工具，使用Swagger UI強(qiáng)大的富文本表現(xiàn)形式可定制化的來(lái)描述Web API的功能，并且包含內(nèi)置的公共方法測(cè)試工具。
1.7-TPL
- 任務(wù)并行庫(kù)（TPL）是System.Threading.Tasks命名空間中的一組公共類(lèi)型和API
- TPL動(dòng)態(tài)的擴(kuò)展并發(fā)度，以最有效的使用可用的處理器。通過(guò)使用TPL，您可以最大限度的提高代碼的性能，同時(shí)專(zhuān)注于您的代碼業(yè)務(wù)。
- 從.NETFramework4開(kāi)始，TPL是編寫(xiě)多線程和并行代碼的首選方式。
二、在ASP.NET Core Web API中使用Swagger UI
2.1-創(chuàng)建一個(gè)WebAPI項(xiàng)目
2.2-下載、安裝、引入【Swashbuckle.AspNetCore】包
右擊【解決方案】，然后點(diǎn)擊【管理Nuget包】，搜索【Swashbuckle.AspNetCore】包，點(diǎn)擊【安裝】即可，博主這里下載的是【最新穩(wěn)定版5.6.3】。
2.3-配置Swagger中間件（注冊(cè) Swagger 服務(wù)）
在【Startup.cs】文件中的【ConfigureService】類(lèi)中引入命名空間，并注冊(cè)Swagger服務(wù)并配置文檔信息。
//引入命名空間
using Microsoft.OpenApi.Models;
//注冊(cè)Swagger
services.AddSwaggerGen(u => {
u.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Version = "Ver:1.0.0",//版本
Title = "xxx后臺(tái)管理系統(tǒng)",//標(biāo)題
Description = "xxx后臺(tái)管理系統(tǒng)：包括人員信息、團(tuán)隊(duì)管理等。",//描述
Contact=new Microsoft.OpenApi.Models.OpenApiContact {
Name="西瓜程序猿",
Email="xxx@qq.com"
}
});
});
如果安裝的 Swashbuckle.AspNetCore Nuget包版本<= 3.0.0，寫(xiě)法略有不同。將 【OpenApiInfo】 替換成 【Info】 即可。
services.AddSwaggerGen(x =>
{
x.SwaggerDoc("v1", new Info() { Title = "Web Api", Version = "v1" });
});
2.4-啟用Swagger中間件
在【Startup.cs】文件中的【Configure】類(lèi)中啟用Swagger中間件，為生成的JSON文檔和SwaggerUI提供服務(wù)。
//啟用Swagger中間件
app.UseSwagger();
//配置SwaggerUI
app.UseSwaggerUI(u =>
{
u.SwaggerEndpoint("/swagger/v1/swagger.json", "WebAPI_v1");
});
2.5-運(yùn)行項(xiàng)目即可
2.5.1-如果我們直接運(yùn)行項(xiàng)目，會(huì)出現(xiàn)這樣的界面，說(shuō)明我們的Web API程序沒(méi)有問(wèn)題。
2.5.2-然后我們?cè)诘刂窓谥休斎搿緎wagger/v1/swagger.json】。
可以看到瀏覽器出現(xiàn)這樣的界面，如果出現(xiàn)這樣的界面，說(shuō)明Swagger也沒(méi)有問(wèn)題。
注意：按照2.5.1在地址欄中的【swagger/v1/swagger.json】需要與在【Startup.cs】文件中的【Configure】類(lèi)中啟用Swagger中間件添加的代碼保持一致，因?yàn)檫@段代碼就是自動(dòng)生成JSON文件的，你配置的路徑和JSON文件地址是什么，就在瀏覽器中輸入對(duì)應(yīng)的即可。
2.5.3-以上步驟都沒(méi)問(wèn)題的話，然后我們地址欄中輸入【swagger/index.html】。
如果能出現(xiàn)以下界面，說(shuō)明SwaggerUI也沒(méi)有問(wèn)題，都全部正常了。
2.6-如果想每次運(yùn)行都默認(rèn)直接到Swagger的頁(yè)面
2.6.1-打開(kāi)【launchSettings.json】這個(gè)文件。
2.6.2-然后將【launchUrl】的值從【weatherforecast】修改成【swagger】。
2.6.3-然后運(yùn)行項(xiàng)目就直接進(jìn)入Swagger首頁(yè)了。
2.7-描述信息詳細(xì)講解
三、啟用XML注釋
3.1-雙擊解決方案
3-2-然后進(jìn)入這個(gè)頁(yè)面，加上這個(gè)代碼
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
3-3.在【Startup.cs】文件中的【ConfigureService】類(lèi)中注冊(cè)讀取XML信息的Swagger。
#region 讀取xml信息
// 使用反射獲取xml文件，并構(gòu)造出文件的路徑
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 啟用xml注釋?zhuān)摲椒ǖ诙€(gè)參數(shù)啟用控制器的注釋?zhuān)J(rèn)為false.
u.IncludeXmlComments(xmlPath, true);
#endregion
注意：
- 對(duì)于Linux或者非Windows操作系統(tǒng)，文件名和路徑區(qū)分大小寫(xiě)。例如“MyWebApiUseSwagger.xml”文件在Windows上有效，但在CentOS上是無(wú)效的。
- 獲取應(yīng)用程序路徑，建議采用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來(lái)獲取
四、實(shí)例
4.1-寫(xiě)一個(gè)實(shí)例：在【W(wǎng)eatherForecastController】控制器中寫(xiě)一個(gè)方法。
4.2-寫(xiě)上以下代碼然后進(jìn)行請(qǐng)求。
/// <summary>
/// 這是一個(gè)例子
/// </summary>
/// <remarks>
/// 描述：這是一個(gè)帶參數(shù)的GET請(qǐng)求
/// Web API
/// </remarks>
/// <param name="id">主鍵ID</param>
/// <returns>測(cè)試字符串</returns>
[HttpGet("{id}")]
public ActionResult<string> Get(int id) {
return $"你請(qǐng)求的ID是：{id}";
}
4.3-可以看到【XML注釋】起作用了，然后調(diào)用也成功了。
五、小知識(shí)點(diǎn)
5.1-當(dāng)入?yún)?出參返回object或者匿名類(lèi)時(shí)，也需要加上注釋怎么辦？
（1）在方法中加上以下特性：
[ProducesResponseType(typeof(xxx),200)]
（2）在Remarks節(jié)點(diǎn)下進(jìn)行注釋?zhuān)?br>
5.2-如何隱藏接口：有接口但是不想讓別人看到？
在需要進(jìn)行隱藏的接口上加上以下特性即可：
[ApiExplorerSettings(IgnoreApi =true)]
5.3-設(shè)置路由前綴/自定義頭內(nèi)容/網(wǎng)頁(yè)標(biāo)題
如果不想加上"swagger"，而輸入5000即可訪問(wèn)，也可以自定義路由前綴，加上以下代碼即可。
5.3-自定義首頁(yè)
（1）新建一個(gè)【index.html】，右擊該文件，點(diǎn)擊【屬性】，進(jìn)行設(shè)置相關(guān)操作。
（2）在Startup.cs進(jìn)行配置。
（3）靜態(tài)頁(yè)面下載地址：
https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html
5.4-開(kāi)啟JWT認(rèn)證
（1）在Startup.cs進(jìn)行配置。
#region 開(kāi)啟JWT
u.OperationFilter<SecurityRequirementsOperationFilter>();
u.AddSecurityDefinition("oauth2", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
{
Description = "JWT授權(quán)(數(shù)據(jù)將在請(qǐng)求頭中進(jìn)行傳輸)直接在下框中輸入Bearer { token } (注意兩者之間是一個(gè)空格) ",
Name = "Authorization",
In = Microsoft.OpenApi.Models.ParameterLocation.Header,//jwt默認(rèn)存放Authorazation信息的位置（請(qǐng)求頭中）
Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey
});
#endregion
（2）下載包，注意版本號(hào)問(wèn)題，盡量保持一致，不然會(huì)報(bào)錯(cuò)。
（3）然后將接口加上權(quán)限，去請(qǐng)求該接口，可以看到請(qǐng)求頭中會(huì)有以下信息了。
5.5-使用Cookie持久化存儲(chǔ)Token，解決每次刷新需要重新輸入Token授權(quán)
下載相關(guān)資源?？梢栽L問(wèn)下載（如果失效了，請(qǐng)聯(lián)系我[西瓜程序猿]）。
下載地址（編碼：yRLCRp81）：https://yongteng.lanzoub.com/iG3Be16ayltc
密碼：anum
目錄結(jié)構(gòu)：
（1）在【index.html】文件導(dǎo)入abp.js/swagger.js文件。
（2）在【swagger.js】里面需要注意請(qǐng)求授權(quán)地址。
（3）后端授權(quán)邏輯。
文章來(lái)源：http://www.zghlxwxcb.cn/news/detail-622544.html
原文鏈接：https://www.cnblogs.com/kimiliucn/p/17602073.html文章來(lái)源地址http://www.zghlxwxcb.cn/news/detail-622544.html
到了這里，關(guān)于.NET Core WebAPI中使用Swagger（完整教程）的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
