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.Swagger：將SwaggerDocument物件公開為JSON終結點的Swagger物件模型和中間件，
Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成SwaggerDocument物件的Swagger生成器，它通常與Swagger終結點中間件結合，以自動公開Swagger JSON，
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本，它解釋Swagger JSON以構建描述Web API功能的可自定義的豐富體驗，它包括針對公共方法的內置測驗工具，
安裝Swashbuckle組件方法有兩種：
--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入門
轉載請註明出處，本文鏈接：https://www.uj5u.com/net/44892.html
標籤：.NET Core