.NET Core WebAPI中使用Swagger（完整教程）

来源:https://www.cnblogs.com/kimiliucn/archive/2023/08/02/17602073.html
-Advertisement-
Play Games

Swagger是一個規範且完整的框架，用於生成、描述、調試和可視化Restfull風格的Web服務。Swagger的目標是對Rest API定義一個標準且和語言無關的介面，可以讓人和電腦擁有無需訪問源碼、文檔或網路流量監控就可以發現和連接服務的能力。當通過Swagger進行正確定義，用於可以理解遠... ...


一、Swagger簡介

1.1-什麼是Swagger?

  • Swagger是一個規範且完整的框架，用於生成、描述、調試和可視化Restfull風格的Web服務。
  • Swagger的目標是對Rest API定義一個標準且和語言無關的介面，可以讓人和電腦擁有無需訪問源碼、文檔或網路流量監控就可以發現和連接服務的能力。當通過Swagger進行正確定義，用於可以理解遠程服務並使用最少邏輯與遠程服務進行交互。與為底層編程所實現的介面類似，Swagger消除了調用服務時可能會有的猜測。

1.2-Swagger有什麼優勢？

  • 支持API自動生成同步的線上文檔：使用Swagger後可以直接通過代碼生成文檔，不需要自己去手動編寫介面文檔了，對程式員來說是非常方便。
  • 提供Web頁面線上測試API：光有文檔還不夠，Swagger生成的文檔還支持線上測試。參數和格式都一定定義好了，直接在界面上輸出參數對應的值即可在先測試介面。
  • Swagger可以生成客戶端SDK代碼用於各種不同平臺的實現。
  • Swagger文件可以在許多不同的平臺上從代碼註釋中自動生成。
  • Swagger有一個強大的社區，裡面有許多強悍的貢獻者。

1.3-Swagger、OpenAPI3.0、Restful API的區別？

  • Open API：OpenAPI是規範的正式名稱。該規範的開發時由OpenAPI Initative推動的。該提倡涉及不同領域的30個組織——包括Microsoft、Google、IBM和CapitalOne.
  • Swagger：實現OpenAPI規範的工具之一。
  • RestfulAPI：是一種WebAPI設計架構風格。其中Rest即Represntaional State Transfer的縮寫，可以翻譯為"狀態表述轉換"。是目前比較成熟的一套互聯網應用程式的API設計架構風格OpenAPI規範即是這個架構風格的具體實現規範。

1.4-Swagger工具

image.png

1.5-Swagger UI工具主要功能

  • 介面的文檔線上自動生成
  • 功能測試等

1.6-Swashbuckle組件

  • Swashbuckle是.NET Core中對Swagger的封裝，他有2個核心組件：
    • Swashbuckle.SwaggerGen：提供生成對象、方法、返回類型等JSON Swagger文檔的功能。
    • Swashbuckle.SwaggerUI：是一個嵌入式版本的SwaggerUI工具，使用Swagger UI強大的富文本表現形式可定製化的來描述Web API的功能，並且包含內置的公共方法測試工具。

1.7-TPL

  • 任務並行庫（TPL）是System.Threading.Tasks命名空間中的一組公共類型和API
  • TPL動態的擴展併發度，以最有效的使用可用的處理器。通過使用TPL，您可以最大限度的提高代碼的性能，同時專註於您的代碼業務。
  • 從.NETFramework4開始，TPL是編寫多線程和並行代碼的首選方式。

二、在ASP.NET Core Web API中使用Swagger UI

2.1-創建一個WebAPI項目

image.png

2.2-下載、安裝、引入【Swashbuckle.AspNetCore】包

右擊【解決方案】，然後點擊【管理Nuget包】，搜索【Swashbuckle.AspNetCore】包，點擊【安裝】即可，博主這裡下載的是【最新穩定版5.6.3】。
image.png

2.3-配置Swagger中間件（註冊 Swagger 服務）

在【Startup.cs】文件中的【ConfigureService】類中引入命名空間，並註冊Swagger服務並配置文檔信息。

//引入命名空間
using Microsoft.OpenApi.Models;

//註冊Swagger
services.AddSwaggerGen(u => {
    u.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
                 {
                     Version = "Ver:1.0.0",//版本
                     Title = "xxx後臺管理系統",//標題
                     Description = "xxx後臺管理系統：包括人員信息、團隊管理等。",//描述
                     Contact=new Microsoft.OpenApi.Models.OpenApiContact { 
                         Name="西瓜程式猿",
                         Email="[email protected]"
                         }
                 });
});

如果安裝的 Swashbuckle.AspNetCore Nuget包版本<= 3.0.0，寫法略有不同。將 【OpenApiInfo】 替換成 【Info】 即可。

services.AddSwaggerGen(x =>
{

    x.SwaggerDoc("v1", new Info() { Title = "Web Api", Version = "v1" });

});

2.4-啟用Swagger中間件

在【Startup.cs】文件中的【Configure】類中啟用Swagger中間件，為生成的JSON文檔和SwaggerUI提供服務。

 //啟用Swagger中間件
app.UseSwagger();
//配置SwaggerUI
app.UseSwaggerUI(u =>
                 {
                     u.SwaggerEndpoint("/swagger/v1/swagger.json", "WebAPI_v1");
                 });

2.5-運行項目即可

2.5.1-如果我們直接運行項目，會出現這樣的界面，說明我們的Web API程式沒有問題。
image.png

2.5.1-然後我們在地址欄中輸入【swagger/v1/swagger.json】。
image.png

可以看到瀏覽器出現這樣的界面，如果出現這樣的界面，說明Swagger也沒有問題。
image.png

註意：按照2.5.1在地址欄中的【swagger/v1/swagger.json】需要與在【Startup.cs】文件中的【Configure】類中啟用Swagger中間件添加的代碼保持一致，因為這段代碼就是自動生成JSON文件的，你配置的路徑和JSON文件地址是什麼，就在瀏覽器中輸入對應的即可。
image.png

2.5.1-以上步驟都沒問題的話，然後我們地址欄中輸入【swagger/index.html】。
image.png

如果能出現以下界面，說明SwaggerUI也沒有問題，都全部正常了。
image.png

2.6-如果想每次運行都預設直接到Swagger的頁面

2.6.1-打開【launchSettings.json】這個文件。
image.png

2.6.2-然後將【launchUrl】的值從【weatherforecast】修改成【swagger】。
image.png

2.6.3-然後運行項目就直接進入Swagger首頁了。

2.7-描述信息詳細講解

image.png
image.png

三、啟用XML註釋

3.1-雙擊解決方案
image.png

3-2-然後進入這個頁面，加上這個代碼
image.png

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>

3-3.在【Startup.cs】文件中的【ConfigureService】類中註冊讀取XML信息的Swagger。
image.png

  #region 讀取xml信息
     // 使用反射獲取xml文件，並構造出文件的路徑
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // 啟用xml註釋，該方法第二個參數啟用控制器的註釋，預設為false.
    u.IncludeXmlComments(xmlPath, true);
  #endregion

註意：

  • 對於Linux或者非Windows操作系統，文件名和路徑區分大小寫。例如“MyWebApiUseSwagger.xml”文件在Windows上有效，但在CentOS上是無效的。
  • 獲取應用程式路徑，建議採用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

四、實例

4.1-寫一個實例：在【WeatherForecastController】控制器中寫一個方法。
image.png

4.2-寫上以下代碼然後進行請求。

/// <summary>
/// 這是一個例子
/// </summary>
/// <remarks>
/// 描述：這是一個帶參數的GET請求
/// Web API
/// </remarks>
/// <param name="id">主鍵ID</param>
/// <returns>測試字元串</returns>
[HttpGet("{id}")]
public ActionResult<string> Get(int id) {
     return $"你請求的ID是：{id}";
}

4.3-可以看到【XML註釋】起作用了，然後調用也成功了。
image.png

五、小知識點

5.1-當入參/出參返回object或者匿名類時，也需要加上註釋怎麼辦？

image.png
image.png

（1）在方法中加上以下特性：

 [ProducesResponseType(typeof(xxx),200)]

image.png

（2）在Remarks節點下進行註釋：
image.png
image.png

5.2-如何隱藏介面：有介面但是不想讓別人看到？

在需要進行隱藏的介面上加上以下特性即可：

  [ApiExplorerSettings(IgnoreApi =true)]

image.png

5.3-設置路由首碼/自定義頭內容/網頁標題

如果不想加上"swagger"，而輸入5000即可訪問，也可以自定義路由首碼，加上以下代碼即可。
image.png
image.png

5.3-自定義首頁

（1）新建一個【index.html】，右擊該文件，點擊【屬性】，進行設置相關操作。
image.png
image.png
（2）在Startup.cs進行配置。
image.png
（3）靜態頁面下載地址：

https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html

5.4-開啟JWT認證

（1）在Startup.cs進行配置。
image.png

 #region 開啟JWT
   u.OperationFilter<SecurityRequirementsOperationFilter>();

	u.AddSecurityDefinition("oauth2", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
	{
		Description = "JWT授權(數據將在請求頭中進行傳輸)直接在下框中輸入Bearer { token } (註意兩者之間是一個空格) ",
  		Name = "Authorization",
		In = Microsoft.OpenApi.Models.ParameterLocation.Header,//jwt預設存放Authorazation信息的位置（請求頭中）
		Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey
	});
#endregion

（2）下載包，註意版本號問題，儘量保持一致，不然會報錯。
image.png
（3）然後將介面加上許可權，去請求該介面，可以看到請求頭中會有以下信息了。
image.png

5.5-使用Cookie持久化存儲Token，解決每次刷新需要重新輸入Token授權

目錄結構：
image

（1）在【index.html】文件導入abp.js/swagger.js文件。
image.png
（2）在【swagger.js】裡面需要註意請求授權地址。
image.png
（3）後端授權邏輯。
image.png
image.png
image.png


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

-Advertisement-
Play Games
更多相關文章
  • 一周學會python1-開始
    大家好，我是三友~~ 今天來跟大家聊一聊Spring的9大核心基礎功能。 其實最近有小伙伴私信問我怎麼不寫文章了，催更來了 其實我不是不寫，而是一直在寫這篇文章，只不過令我沒想到的是，從前期的選題、準備、翻源碼、動手到寫完，前後跨度接近一個月的時間，花了好幾個周末，寫了三萬字，最終才算完成。 所以如 ...
  • 京東又開源一個新框架，用起來真優雅！
    DripTable 是京東零售推出的一款用於企業級中後臺的動態列表解決方案，項目基於 React 和 JSON Schema，旨在通過簡單配置快速生成頁面動態列表來降低列表開發難度、提高工作效率。 DripTable 目前包含以下子項目：drip-table、drip-table-generator ...
  • D3JS教程_編程入門自學教程_菜鳥教程-免費教程分享
    ## 教程簡介 D3是Data-Driven Documents的縮寫，D3.js是一個基於數據管理文檔的資源JavaScript庫。 D3 是最有效的數據可視化框架之一。它允許開發人員在 HTML、CSS 和 SVG 的幫助下在瀏覽器中創建動態的互動式數據可視化。數據可視化是將過濾後的數據以圖片和 ...
  • python教程 入門學習筆記 第4天 數據類型 獲取數據類型 字元串拼接
    數據類型 1、能直接處理的基本數據類型有5個：整型、浮點型、字元串、布爾值、空 1）整型（int）=整數，例如0至9，-1至-9，100，-8180等，人數、年齡、頁碼、門牌號等 沒有小數位的數字，是整型 2）浮點型（float）=小數，例如金額、身高、體重、距離、長度、π等 精確到小數位的數字，是 ...
  • Python 3.12 搶先看——關於 f-string 的改動
    # Python 3.12 搶先看——關於 f-string 的改動 哈嘍大家好，我是鹹魚 相信小伙伴們對 python 中的 f-string 都不陌生 f-string 是格式化字元串的縮寫，是以小寫或大寫字母 F 為首碼的字元串文本 f-string 提供簡潔明瞭的語法，**允許對變數和表達式 ...
  • 4、Spring之依賴註入
    > 依賴註入就是對類的屬性進行賦值 ## 4.1、環境搭建 > 創建名為spring_ioc_xml的新module，過程參考[3.1節](https://www.cnblogs.com/Javaer1995/p/17570068.html "3.1節") ### 4.1.1、創建spring配置文 ...
  • quarkus依賴註入之四：選擇註入bean的高級手段
    ### 歡迎訪問我的GitHub > 這裡分類和彙總了欣宸的全部原創(含配套源碼)：[https://github.com/zq2599/blog_demos](https://github.com/zq2599/blog_demos) ### 本篇概覽 - 本文是《quarkus依賴註入》系列的第 ...
  • .Net Core Autofac
    [toc] # Autofac Autofac 是一款超贊的.NET IoC 容器 . 它管理類之間的依賴關係, 從而使 應用在規模及複雜性增長的情況下依然可以輕易地修改 . 它的實現方式是將常規的.net類當做 組件 處理. 控制反轉背後的核心思想是, 我們不再將應用中的類捆綁在一起, 讓類自己去 ...
一周排行
    -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.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類