一. 基本概念

1.背景

　　使用 Web API 時(shí)，了解其各種方法對(duì)開(kāi)發(fā)人員來(lái)說(shuō)可能是一項(xiàng)挑戰(zhàn)。 Swagger 也稱為OpenAPI，解決了為 Web API 生成有用文檔和幫助頁(yè)的問(wèn)題。 它具有諸如交互式文檔、客戶端 SDK生成和 API 可發(fā)現(xiàn)性等優(yōu)點(diǎn)，目前有兩種實(shí)現(xiàn)方式：

?(1).Swashbuckle.AspNetCore: 是一個(gè)開(kāi)源項(xiàng)目，用于生成 ASP.NET Core Web API 的 Swagger 文檔。（本節(jié)重點(diǎn)介紹）

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

2.什么是 Swagger/OpenAPI？

　　Swagger 是一個(gè)與語(yǔ)言無(wú)關(guān)的規(guī)范，用于描述 REST API。 Swagger 項(xiàng)目已捐贈(zèng)給 OpenAPI 計(jì)劃，現(xiàn)在它被稱為開(kāi)放 API。 這兩個(gè)名稱可互換使用，但 OpenAPI 是首選。?它允許計(jì)算機(jī)和人員了解服務(wù)的功能，而無(wú)需直接訪問(wèn)實(shí)現(xiàn)（源代碼、網(wǎng)絡(luò)訪問(wèn)、文檔）。 其中一個(gè)目標(biāo)是盡量減少連接取消關(guān)聯(lián)的服務(wù)所需的工作量。 另一個(gè)目標(biāo)是減少準(zhǔn)確記錄服務(wù)所需的時(shí)間。

3.Swagger 規(guī)范

　　Swagger 流的核心是 Swagger 規(guī)范，默認(rèn)情況下是名為 swagger.json 的文檔 。 它由 Swagger 工具鏈（或其第三方實(shí)現(xiàn)）根據(jù)你的服務(wù)生成。 它描述了 API 的功能以及使用 HTTP 對(duì)其進(jìn)行

訪問(wèn)的方式。 它驅(qū)動(dòng) Swagger UI，并由工具鏈用來(lái)啟用發(fā)現(xiàn)和客戶端代碼生成。

4.Swagger UI

　　Swagger UI提供了基于 Web 的 UI，它使用生成的 Swagger 規(guī)范提供有關(guān)服務(wù)的信息。?Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本，因此可使用中間件注冊(cè)調(diào)用將該嵌入式版本托管在 ASP.NET Core 應(yīng)用中。

二.?基于Swashbuckle.AspNetCore實(shí)現(xiàn)

【訪問(wèn)地址：http://localhost:1572/swagger/index.html】

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

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

1 public void ConfigureServices(IServiceCollection services)2 {3 services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);4 5 // 注冊(cè)Swagger服務(wù)，聲明一個(gè)或多個(gè)文檔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 提供服務(wù)。

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 //要在應(yīng)用的根(http://localhost:<port>/) 處提供 Swagger UI，請(qǐng)將 RoutePrefix 屬性設(shè)置為空字符串： 18 //c.RoutePrefix = string.Empty; 19 }); 20 app.UseMvc(); 21 }

　　補(bǔ)充：配置完前三步后，通過(guò)訪問(wèn)【http://localhost:1572/swagger/v1/swagger.json】，返回一個(gè)json格式的文件。通過(guò)訪問(wèn)【http://localhost:1572/swagger/index.html】返回UI頁(yè)面，這個(gè)時(shí)候發(fā)現(xiàn)UI頁(yè)面中沒(méi)有注釋，很尷尬。

4. 開(kāi)啟注釋

(1).選中當(dāng)前項(xiàng)目，右鍵屬性，進(jìn)入“生成”頁(yè)面，將“xml文檔文件”的選項(xiàng)卡勾上。

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

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

1 public void ConfigureServices(IServiceCollection services)2 {3 services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);4 5 // 注冊(cè)Swagger服務(wù)，聲明一個(gè)或多個(gè)文檔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下技巧：

　　開(kāi)啟注釋以后，發(fā)現(xiàn)代碼中很多提示沒(méi)有加注釋，而這些注釋我是不想加的，那么怎么去掉呢，通過(guò)觀察錯(cuò)誤列表，發(fā)現(xiàn)這些提示都是CS1591，然后選中項(xiàng)目，右鍵屬性，進(jìn)入生成頁(yè)面，在禁止顯示錯(cuò)誤警告的欄目中，加上“1591”即可解決。

?

5. 測(cè)試

　　再次訪問(wèn)【http://localhost:1572/swagger/index.html】，發(fā)現(xiàn)注釋都有了，可以開(kāi)心的進(jìn)行測(cè)試了，到這里已經(jīng)大功告成了。

?

?

?

6.分享幾個(gè)擴(kuò)展功能

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

?

總結(jié)

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

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。