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

来源:https://www.cnblogs.com/Zenderblogs/archive/2019/12/12/12027526.html
-Advertisement-
Play Games

認識Swagger Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為伺服器以同樣的速度來更新。文件的方法，參數和模型緊密集成到伺服器端的代碼，允許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 = "[email protected]",
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 = "[email protected]",
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/


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • .NET Core 3終結點不能映射控制器
    今天在學.net core的時候發現了一個問題，終結點死活映射不了自己添加的控制器，後經過研究發現解決方法，可能這個問題不應該叫做問題，可是我是初學者，就把這個問題給拎出來。本人開發環境 VS2019+.Net Core 3.1,問題重現過程： 1.新建Web Core項目，選擇空項目 2.新建文件 ...
  • C# dictionary to bytes and bytes convert to dictionary
    static byte[] GetBytesFromDic(Dictionary<string,string> dic) { if(dic==null || !dic.Any()) { return null; } using (MemoryStream ms = new MemoryStream( ...
  • Winform中實現將照片剪貼到系統剪切板中(附代碼下載)
    場景 效果 點擊剪切按鈕 點擊粘貼按鈕 註： 博客主頁： https://blog.csdn.net/badao_liumang_qizhi 關註公眾號 霸道的程式猿 獲取編程相關電子書、教程推送與免費下載。 實現 新建一個form窗體，設計佈局如下 主要是有兩個PictureBox控制項以及四個按鈕 ...
  • 非同步載入樹節點
    1 using System; 2 using System.Collections.Generic; 3 using System.ComponentModel; 4 using System.Data; 5 using System.Drawing; 6 using System.Text; 7 ...
  • Redis主從複製+哨兵簡單配置
    項目中考慮到容災、性能以及容量，一般會使用集群方式搭建redis。而當redis主伺服器存在故障，為了redis仍能正常運行，可以搭建redis哨兵，通過選舉方式重新建立主從關係。本文簡單講述主從建立和哨兵的配置。本機測試redis為Redis-x64-3.2.100（Windows下載地址：htt ...
  • Winform中實現批量文件複製(附代碼下載)
    場景 效果 將要批量複製的文件拖拽到窗體中，然後點擊下邊選擇目標文件夾，然後點擊複製按鈕。 註： 博客主頁： https://blog.csdn.net/badao_liumang_qizhi 關註公眾號 霸道的程式猿 獲取編程相關電子書、教程推送與免費下載。 實現 新建一個窗體，佈局設計如下 上面 ...
  • Winform中實現自定義屏保效果(附代碼下載)
    場景 效果 註： 博客主頁： https://blog.csdn.net/badao_liumang_qizhi 關註公眾號 霸道的程式猿 獲取編程相關電子書、教程推送與免費下載。 實現 新建form窗體，窗體中設計佈局如下，一個Panel中拖拽四個label，然後添加兩個Button，再添加一個T ...
  • Winform中實現向窗體中拖放照片並顯示以及拖放文件夾顯示樹形結構(附代碼下載)
    場景 向窗體中拖拽照片並顯示效果 向窗體中拖拽文件夾並顯示樹形結構效果 註： 博客主頁： https://blog.csdn.net/badao_liumang_qizhi 關註公眾號 霸道的程式猿 獲取編程相關電子書、教程推送與免費下載。 實現 新建一個窗體，在窗體中拖拽一個Panel控制項，再在P ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類