NetCore 3.0 中使用Swagger生成Api說明文檔及升級報錯緣由

認識Swagger

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。
做用：

1. 接口的文檔在線自動生成。
2. 功能測試。

爲何使用Swagger做爲REST APIs文檔生成工具

1. Swagger 能夠生成一個具備互動性的API控制檯，開發者能夠用來快速學習和嘗試API。
2. Swagger 能夠生成客戶端SDK代碼用於各類不一樣的平臺上的實現。
3. Swagger 文件能夠在許多不一樣的平臺上從代碼註釋中自動生成。
4. Swagger 有一個強大的社區，裏面有許多強悍的貢獻者。

安裝Nuget包搜索Swashbuckle.AspNetCore

由於是.NetCore3.0 ,因此必定要勾選包括預覽發行版，安裝最新預發行版 5.0.0-rc4,千萬不要安裝最新穩定版。穩定版會報錯。
穩定版報錯信息：

1 Some services are not able to be constructed (Error while validating the service descriptor 'ServiceType:
2 Swashbuckle.AspNetCore.Swagger.ISwaggerProvider Lifetime: Transient ImplementationType: 3 Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator': Failed to compare two elements in the array.)
4 (Error while validating the service descriptor 'ServiceType: Swashbuckle.AspNetCore.SwaggerGen.ISchemaRegistryFactory Lifetime:
5 Transient ImplementationType: Swashbuckle.AspNetCore.SwaggerGen.SchemaRegistryFactory': Failed to compare two elements in the array.)

解決辦法就是3.0版本中要安裝如今預覽發行版5.0.0-rc4

在.NetCore3.0中 配置Swagger 也發生變化，
由之前的

1 services.AddSwaggerGen(c =>
2 { 3 　　c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" }); 4 });

變動爲

1 services.AddSwaggerGen(c =>
2  { 3        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); 4  });

其中最大的變化就是Info這裏，在之前2.0版本中是由Swagger來管理的。在3.0版本中統一變動爲 OpenApi管理，OpenApi 在官方文檔中介紹爲是用於管理項目內 OpenAPI 引用的 .NET Core 全局工具。

參考地址：(https://docs.microsoft.com/zh-cn/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-3.1 "使用 OpenAPI 工具開發 ASP.NET Core 應用")

因此在添加完Swagger 包後，還要在項目中添加Microsoft.OpenApi包

註冊Swagger

 1 public void ConfigureServices(IServiceCollection services)  2 {  3 
 4 services.AddControllers();  5 
 6 services.AddSwaggerGen(c =>  7 {  8 c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });  9 }); 10 
11 }

配置Swagger UI

 1 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  2 {  3 if (env.IsDevelopment())  4 {  5 app.UseDeveloperExceptionPage();  6 }  7 app.UseHttpsRedirection();  8 app.UseRouting();  9 app.UseAuthorization(); 10 //啓用Swagger
11 app.UseSwagger(); 12 //配置Swagger UI
13 app.UseSwaggerUI(c => 14 { 15 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API"); //注意中間段v1要和上面SwaggerDoc定義的名字保持一致
16 }); 17 app.UseEndpoints(endpoints => 18 { 19 endpoints.MapControllers(); 20 }); 21 }

啓動項目

CTRL+F5啓動項目，並導航到 http://localhost:port/swagger 經過Swagger UI遊覽API文檔

Swagger的高級用法（自定義擴展）

在 AddSwaggerGen 方法的進行以下的配置操做會添加諸如做者、許可證和說明信息等：

 1 services.AddSwaggerGen(c =>
 2  {  3            c.SwaggerDoc("v1", new OpenApiInfo  4  {  5                     Title = "My API",  6                     Version = "v1",  7                     Description = "API文檔描述",  8                     Contact = new OpenApiContact  9  { 10                         Email = "8596007@qq.com", 11                         Name = "開源NetCore", 12                         Url = new Uri("http://www.netcore.pub/") 13  }, 14                     License = new OpenApiLicense 15  { 16                         Name = "許可證名稱", 17                         Url = new Uri("http://www.netcore.pub/") 18  } 19  }); 20  });

Swagger UI 顯示版本的信息以下圖所示

爲API接口方法添加註釋

你們先點開API，展開以下圖所示，但是沒有註釋呀，怎麼添加註釋呢？

按照下列代碼所示用三個/添加文檔註釋，以下所示

 1 /// <summary>
 2 /// 這是一個API註釋  3 /// </summary>
 4 /// <returns></returns>
 5 [HttpGet]  6 public IEnumerable<WeatherForecast> Get()  7  {  8             var rng = new Random();  9             return Enumerable.Range(1, 5).Select(index => new WeatherForecast 10  { 11                 Date = DateTime.Now.AddDays(index), 12                 TemperatureC = rng.Next(-20, 55), 13                 Summary = Summaries[rng.Next(Summaries.Length)] 14  }) 15  .ToArray(); 16 }

而後運行項目，回到Swagger UI中去查看註釋是否出現了呢

仍是沒出現？一臉懵逼？？？ 別急往下看！

啓用XML註釋

可以使用如下方法啓用 XML 註釋：

右鍵單擊「解決方案資源管理器」中的項目，而後選擇「屬性」
查看「生成」選項卡的「輸出」部分下的「XML 文檔文件」框

啓用 XML 註釋後會爲未記錄的公共類型和成員提供調試信息。若是出現不少警告信息 例如，如下消息指示違反警告代碼 1591：

1 warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

若是你有強迫症，想取消警告怎麼辦呢？能夠按照下圖所示進行取消

注意上面生成的xml文檔文件的路徑，

注意：

​ 1.對於 Linux 或非 Windows 操做系統，文件名和路徑區分大小寫。 例如，「Kylin.Wiki.xml」文件在 Windows 上有效，但在 CentOS 上無效。

​ 2.獲取應用程序路徑，建議採用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

 1 services.AddSwaggerGen(c =>
 2  {  3                 c.SwaggerDoc("v1", new OpenApiInfo  4  {  5                     Title = "My API",  6                     Version = "v1",  7                     Description = "API文檔描述",  8                     Contact = new OpenApiContact  9  { 10                         Email = "8596007@qq.com", 11                         Name = "開源NetCore", 12                         Url = new Uri("http://www.netcore.pub/") 13  }, 14                     License = new OpenApiLicense 15  { 16                         Name = "許可證名稱", 17                         Url = new Uri("http://www.netcore.pub/") 18  } 19  }); 20                 // 爲 Swagger JSON and UI設置xml文檔註釋路徑
21                 var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工做目錄影響，建議採用此方法獲取路徑）
22                 var xmlPath = Path.Combine(basePath, "Kylin.Wiki.xml"); 23  c.IncludeXmlComments(xmlPath); 24  });

從新生成並運行項目查看一下注釋出現了沒有

經過上面的操做能夠總結出，Swagger UI 顯示上述註釋代碼的元素的內部文本做爲api大的註釋！

固然你還能夠將 remarks 元素添加到 Get 操做方法文檔。 它能夠補充元素中指定的信息，並提供更可靠的 Swagger UI。 元素內容可包含文本、JSON 或 XML。 代碼以下：

 1 /// <summary>
 2 /// 這是一個帶參數的get請求  3 /// </summary>
 4 /// <remarks>
 5 /// 例子:  6 /// Get api/Values/1  7 /// </remarks>
 8 /// <param name="id">主鍵</param>
 9 /// <returns>測試字符串</returns>    
10 public ActionResult<string> Get(int id) 11 { 12       return $"你請求的 id 是 {id}"; 13 }

從新生成下項目，當好到SwaggerUI看到以下所示：

描述響應類型

接口使用者最關心的就是接口的返回內容和響應類型啦。下面展現一下201和400狀態碼的一個簡單例子：

咱們須要在咱們的方法上添加：

[ProducesResponseType(201)]

[ProducesResponseType(400)]

而後添加相應的狀態說明：返回value字符串若是id爲空

最終代碼應該是這個樣子：

 1  /// <summary>
 2  /// 這是一個帶參數的get請求  3  /// </summary>
 4  /// <remarks>
 5  /// 例子:  6  /// Get api/Values/1  7  /// </remarks>
 8  /// <param name="id">主鍵</param>
 9  /// <returns>測試字符串</returns>
10  /// <response code="201">返回value字符串</response>
11 /// <response code="400">若是id爲空</response>  
12  // GET api/values/2
13 [HttpGet("{id}")] 14 [ProducesResponseType(201)] 15 [ProducesResponseType(400)] 16 public ActionResult<string> Get(int id) 17 { 18      return $"你請求的 id 是 {id}"; 19 }

效果以下所示
狀態相應效果

使用SwaggerUI測試api接口

下面咱們經過一個小例子經過SwaggerUI調試下接口吧

點擊一個須要測試的API接口，而後點擊Parameters左右邊的「Try it out 」 按鈕
在出現的參數文本框中輸入參數，以下圖所示的，輸入參數2
點擊執行按鈕，會出現下面所示的格式化後的Response，以下圖所示

好了，今天的在ASP.NET Core WebApi 3.0 中使用Swagger生成api說明文檔教程就到這裏了。但願可以對你們學習在ASP.NET Core中使用Swagger生成api文檔有所幫助！

「開源NetCore，若是以爲個人文章對您有用，請幫助本站成長」 

 

除非註明，文章均由開源 NetCore 整理髮布，歡迎轉載。

轉載請註明本文地址：http://www.netcore.pub/167.html

站長會將優質文章在各大平臺同步更新、推送，歡迎你們訪問、訂閱：

博客園： https://www.cnblogs.com/Zenderblogs/

原文出處：https://www.cnblogs.com/Zenderblogs/p/12027526.html