一. 基本概念

1.背景

　　使用 Web API 時，了解其各種方法對開發人員來說可能是一項挑戰。 Swagger 也稱為OpenAPI，解決了為 Web API 生成有用文檔和幫助頁的問題。 它具有諸如交互式文檔、客戶端 SDK生成和 API 可發現性等優點，目前有兩種實現方式：

?(1).Swashbuckle.AspNetCore: 是一個開源項目，用于生成 ASP.NET Core Web API 的 Swagger 文檔。（本節重點介紹）

?(2).NSwag: 是另一個用于生成 Swagger 文檔并將 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的開源項目。 此外，NSwag 還提供了為 API 生成 C# 和 TypeScript 客戶端代碼的方法。

2.什么是 Swagger/OpenAPI？

　　Swagger 是一個與語言無關的規范，用于描述 REST API。 Swagger 項目已捐贈給 OpenAPI 計劃，現在它被稱為開放 API。 這兩個名稱可互換使用，但 OpenAPI 是首選。?它允許計算機和人員了解服務的功能，而無需直接訪問實現（源代碼、網絡訪問、文檔）。 其中一個目標是盡量減少連接取消關聯的服務所需的工作量。 另一個目標是減少準確記錄服務所需的時間。

3.Swagger 規范

　　Swagger 流的核心是 Swagger 規范，默認情況下是名為 swagger.json 的文檔 。 它由 Swagger 工具鏈（或其第三方實現）根據你的服務生成。 它描述了 API 的功能以及使用 HTTP 對其進行

訪問的方式。 它驅動 Swagger UI，并由工具鏈用來啟用發現和客戶端代碼生成。

4.Swagger UI

　　Swagger UI提供了基于 Web 的 UI，它使用生成的 Swagger 規范提供有關服務的信息。?Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本，因此可使用中間件注冊調用將該嵌入式版本托管在 ASP.NET Core 應用中。

二.?基于Swashbuckle.AspNetCore實現

【訪問地址：http://localhost:1572/swagger/index.html】

1. 通過Nuget安裝程序集【Swashbuckle.AspNetCore】，版本：4.0.1。

2. 將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中。

1 public void ConfigureServices(IServiceCollection services)2 {3 services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);4 5 // 注冊Swagger服務，聲明一個或多個文檔6 services.AddSwaggerGen(c =>7 {8 c.SwaggerDoc("v1", new Info { Title = "Ypf API", Version = "v1" });9 }); 10 11 }

3. 在 Startup.Configure 方法中，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務。

1 public void Configure(IApplicationBuilder app, IHostingEnvironment env)2 {3 if (env.IsDevelopment())4 {5 app.UseDeveloperExceptionPage();6 }7 8 // Enable middleware to serve generated Swagger as a JSON endpoint.9 app.UseSwagger(); 10 11 // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 12 // specifying the Swagger JSON endpoint. 13 app.UseSwaggerUI(c => 14 { 15 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); 16 17 //要在應用的根(http://localhost:<port>/) 處提供 Swagger UI，請將 RoutePrefix 屬性設置為空字符串： 18 //c.RoutePrefix = string.Empty; 19 }); 20 app.UseMvc(); 21 }

　　補充：配置完前三步后，通過訪問【http://localhost:1572/swagger/v1/swagger.json】，返回一個json格式的文件。通過訪問【http://localhost:1572/swagger/index.html】返回UI頁面，這個時候發現UI頁面中沒有注釋，很尷尬。

4. 開啟注釋

(1).選中當前項目，右鍵屬性，進入“生成”頁面，將“xml文檔文件”的選項卡勾上。

（觀察路徑：D:\06-架構之路\05-DotNet Core體系\01-Asp.Net Core體系\05-CoreWebApi\OpenApiDemo\OpenApiDemo.xml，這里建議不要改了）

(2).去ConfigureServices中的AddSwaggerGen方法中，添加3行反射代碼，與步驟1中的OpenApiDemo.xml關聯起來。

1 public void ConfigureServices(IServiceCollection services)2 {3 services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);4 5 // 注冊Swagger服務，聲明一個或多個文檔6 services.AddSwaggerGen(c =>7 {8 c.SwaggerDoc("v1", new Info { Title = "Ypf API", Version = "v1" });9 // 映射生成注釋 10 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; 11 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 12 c.IncludeXmlComments(xmlPath); 13 }); 14 }

PS下技巧：

　　開啟注釋以后，發現代碼中很多提示沒有加注釋，而這些注釋我是不想加的，那么怎么去掉呢，通過觀察錯誤列表，發現這些提示都是CS1591，然后選中項目，右鍵屬性，進入生成頁面，在禁止顯示錯誤警告的欄目中，加上“1591”即可解決。

?

5. 測試

　　再次訪問【http://localhost:1572/swagger/index.html】，發現注釋都有了，可以開心的進行測試了，到這里已經大功告成了。

?

?

?

6.分享幾個擴展功能

　　(1).前面的openapi頁面返回只有200即正常的說明，可以通過[ProducesResponseType(201)][ProducesResponseType(400)]特性，添加這兩個狀態的返回值，?加在下面的GetInfor1上。

?

總結

以上是生活随笔為你收集整理的第十四节：Asp.Net Core WebApi生成在线文档-第十九节的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。