第十九節：Asp.Net Core WebApi生成在線文檔

一. 基本概念

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上。

 

 

 

 

 

 

 

 

 

 

!

• 做       者 : Yaopengfei(姚鵬飛)
• 博客地址 : http://www.cnblogs.com/yaopengfei/
• 聲     明1 : 本人才疏學淺，用郭德綱的話說「我是一個小學生」，若有錯誤，歡迎討論，請勿謾罵^_^。
• 聲     明2 : 原創博客請在轉載時保留原文連接或在文章開頭加上本人博客地址，不然保留追究法律責任的權利。