(29)ASP.NET Core3.1 Swagger(OpenAPI)
1.什麼是Swagger/OpenAPI?
Swagger是一個與語言無關的規範,用於描述REST API。因為Swagger專案已捐贈給OpenAPI計劃,所以也叫OpenAPI。它允許計算機和人員瞭解服務的功能,可以直接線上訪問測試API功能。而Swagger UI提供了基於Web的UI,它使用生成的Swagger規範提供有關服務API的資訊。Swashbuckle和NSwag均包含Swagger UI的嵌入式版本,因此可使用中介軟體註冊呼叫將該嵌入式版本託管在ASP.NET Core應用程式當中。Swagger的核心是Swagger規範,預設情況下是名為swagger.json的文件。它由Swagger工具鏈(或其第三方實現)根據你的服務生成。它描述了API的功能以及使用HTTP對其進行訪問的方式。它驅動Swagger UI,並由工具鏈用來啟用發現和客戶端程式碼生成。
2.NET Swagger實現
NET Swagger實現分為兩大分類:
●Swashbuckle.AspNetCore是一個開源專案,用於生成ASP.NET Core Web API的Swagger文件。
●NSwag是另一個用於生成Swagger文件並將Swagger UI或ReDoc整合到ASP.NET Core Web API中的開源專案。此外,NSwag 還提供了為API生成C#和TypeScript客戶端程式碼的方法。
但是由於工作比較忙,我就不打算兩個型別都講了,我只選擇Swashbuckle.AspNetCore來講解和演示。
3.Swashbuckle主要組成部分
Swashbuckle有三個主要組成部分:
Swashbuckle.AspNetCore.SwaggerGen:從路由、控制器和模型直接生成SwaggerDocument物件的Swagger生成器。它通常與Swagger終結點中介軟體結合,以自動公開Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它解釋Swagger JSON以構建描述Web API功能的可自定義的豐富體驗,它包括針對公共方法的內建測試工具。
--PowerShell Install-Package Swashbuckle.AspNetCore -Version 5.0.0
or
--.NET Core CLI dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0
4.什麼是REST?
我百度一下,度娘解釋是:REST是(Representational State Transfer)“表現層狀態轉移”的縮寫,它是由羅伊·菲爾丁(Roy Fielding)提出的,是用來描述建立HTTP API的標準方法,他發現這四種常用的行為“檢視(view),建立(create),編輯(edit)和刪除(delete)”都可以直接對映到HTTP中已實現的GET、POST、PUT和DELETE方法。
5.配置Swagger中介軟體
將Swagger生成器新增到Startup.ConfigureServices方法中的服務集合中:
//註冊Swagger生成器,定義一個或多個Swagger文件. services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1", Description = "測試描述" }); });
OpenApiInfo物件是用來標識Swagger文件資訊(諸如作者、許可證和說明的資訊),您還可以自定義您的主題的資訊顯示在UI上,詳情配置,我就不多說,大家可以看官網描述,如上述OpenApilnfo資訊配置示例圖:
而在啟動應用程式後並導航到http://localhost:<port>/swagger/v1/swagger.json。生成的描述終結點的文件顯示在Swagger規範(swagger.json)中:
在Startup.Configure方法中,啟用中介軟體為生成的JSON文件和Swagger UI提供服務:
//使中介軟體能夠將生成的Swagger用作JSON端點. app.UseSwagger(); //允許中介軟體為swagger ui(HTML、JS、CSS等)提供服務,指定swagger JSON端點. app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); });
根據上述配置就能夠啟用swagger測試API服務介面了,如下圖所示:
6.XML註釋
swagger還可以把服務API中對應方法名稱,實體屬性註釋給在UI上顯示出來,讓您更加直觀瞭解每個方法使用資訊,並對沒有註釋每個方法進行警告提示,具體啟用XML註釋操作在“解決方案資源管理器”中右鍵單擊該專案,然後選擇“編輯<project_name>.csproj”,手動將突出顯示的行新增到.csproj 檔案:
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
在啟用了XML註釋後,swagger只會針對沒有添加註釋每個方法進行警告提示,而添加了註釋的方法則不會進行警告提示:
而每個添加了註釋的方法會通過在Startup.ConfigureServices/services.AddSwaggerGen中設定Swagger JSON和UI的註釋路徑後:
//設定Swagger JSON和UI的註釋路徑.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath);
會在專案根目錄生成的一個對應專案檔名的XML檔案,而檔案裡面就包含所有已註釋的方法,用於UI上顯示:
在啟動應用程式後,我們會看到每個有註釋方法在左側會有一行文字描述,效果如下圖所示:
如果某個方法或者類下面所有方法不想警告提示,可以通過加入#pragma warning disable宣告遮蔽警告提示:
加入宣告之後,大家會看到警告提示消失了。
7.資料註釋
可以使用System.ComponentModel.DataAnnotations名稱空間中的屬性來標記模型實體,以幫助驅動Swagger UI 元件。將[Required]屬性新增到TodoItem類的Name屬性:
namespace TodoApi.Models { public class TodoItem { public long Id { get; set; } [Required] public string Name { get; set; } [DefaultValue(false)] public bool IsComplete { get; set; } } }
此屬性的狀態會更改掉基礎JSON架構:
而將[Produces("application/json")]屬性新增到API控制器去,這樣做的目的是宣告控制器的操作支援application/json的響應內容型別:
[Produces("application/json")] [Route("api/[controller]")] [ApiController] public class ValuesController : ControllerBase { /// <summary> /// 獲取值 /// </summary> /// <returns></returns> // GET api/values [HttpGet] public async Task<ActionResult<IEnumerable<string>>> Get() { var result = await new GitHubApi().GetUser(); return new string[] { result.id.Value.ToString(), result.login }; } }
“響應內容型別”下拉列表選此內容型別作為控制器的預設GET操作:
Swagger/OpenAPI出現,大大減少開發者除錯時間,增加開發者開發效率,讓開發者更加方便除錯跟直觀瞭解對應服務方法。
參考文獻:
Swashbuckle和ASP.NET Core