什麼是Swagger？
如下引用swagger官方的解釋
Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
Swagger consists of a mix of open source, free and commercially available tools that allow anyone, from technical engineers to street smart product managers to build amazing APIs that everyone loves.
Swagger is built by SmartBear Software, the leader in software quality tools for teams. SmartBear is behind some of the biggest names in the software space, including Swagger, SoapUI and QAComplete.
翻譯過來就是
Swagger 是一套功能強大且易於使用的 API 開發人員工具元件，適用於團隊和個人，支援從設計文件到測試部署的整個 API 生命週期的開發。
Swagger 由多種開源、免費和商業可用的工具組成，允許任何人（從技術工程師到智慧產品經理）構建每個人都喜歡且令人驚歎的 API。
Swagger 由 SmartBear Software 構建，SmartBear Software 是團隊軟體質量工具的領導者。SmartBear 支援軟體領域的一些大腕，包括 Swagger、SoapUI 和 QAComplete。
當然，這些瞭解一下就好了，對我們來說並沒有什麼用，只需要知道他是一個簡便的介面除錯方式即可，接下來我們使用一下swagger。
在NET Core API中使用swagger
1. 建立net core api專案
這裡使用ASP.NET Core 3.1建立WebAPI介面專案，命名為 swaggerDemo，建立如下
建立完成後的專案結構
2. 引入swagger 中介軟體
在nuget裡面引入swagger中介軟體，名稱為 Swashbuckle.AspNetCore
3. 配置swagger中介軟體
在 Startup.cs檔案的ConfigureServices 方法中新增如下程式碼，注意下面的 AddSwaggerGen 方法是用於給 API 文件 新增一些後設資料。
PS：注意，這裡提前說一下，如果沒有寫xml檔案解析，那麼最後的文件是沒有方法的註釋和方法引數的註釋，注意參考下面的第5點。
public void ConfigureServices(IServiceCollection services) { // 新增Swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "我是當前API的名稱", //swagger介面文件：名稱 Version = "v1", //swagger介面文件：版本號 Description = "測試Swagger的使用方法" //swagger介面文件：描述 }); //顯示每個方法的註釋和方法引數的註釋 // 獲取xml檔名 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; // 獲取xml檔案路徑 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); // 新增控制器層註釋，true表示顯示控制器註釋 c.IncludeXmlComments(xmlPath, true); }); services.AddControllers(); }
新增好中介軟體後，在 Startup.cs檔案的Configure 方法中，啟用中介軟體為生成的 JSON 文件和 Swagger UI 提供服務，如下：
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } // begin 新增Swagger有關中介軟體 app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1"); }); // end 新增Swagger有關中介軟體 app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
4. 建立一個api介面控制器
建立一個Home介面的控制器，在Home控制器裡面寫入幾個方法用於測試，如下完整顯示，大家測試的時候用一個就可以了。
注意：這裡route路由可以配置，也可以使用預設的。
using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Mvc; using System; using System.Collections.Generic; using System.IO; using System.Linq; using System.Threading.Tasks; namespace swaggerDemo.Controllers { [ApiController] [Route("api/[controller]")] public class HomeController : ControllerBase { private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; /// <summary> /// 不帶任何引數的Get操作方法 /// </summary> /// <remarks> /// 我是不帶任何引數的Get操作方法 /// </remarks> /// <returns></returns> [HttpGet] public IEnumerable<WeatherForecast> Get() { var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } /// <summary> /// 帶引數的get操作方法 /// </summary> /// <remarks> /// 我是一個帶引數的get操作方法 /// </remarks> /// <param name="str">這是輸入的欄位</param> /// <returns></returns> [HttpGet("{str}")] public ActionResult<string> Get(string str) { return str; } /// <summary> /// 新增資料的操作方法 /// </summary> /// <remarks> /// 我是新增功能 /// </remarks> /// <param name="value">這是輸入的欄位</param> [HttpPost] public void Post([FromBody] string value) { } /// <summary> /// （提交檔案）修改資料的操作方法 /// </summary> /// <remarks> /// 我是修改功能 /// </remarks> /// <param name="file">檔名稱</param> /// <param name="id">主鍵</param> [HttpPut("{id}")] public void Put(IFormFile file, int id) { } /// <summary> /// 刪除資料的操作方法 /// </summary> /// <remarks> /// 我是刪除功能 /// </remarks> /// <param name="id">主鍵</param> [HttpDelete("{id}")] public void Delete(int id) { } } }
5. 設定顯示註釋
到這裡我們的Swagger api文件是沒有註釋的，我們新增一下顯示註釋的操作。
點選 swaggerDemo 右鍵-》屬性，點選 生成，把xml文件檔案勾選，勾選後會自動填充資料，裡面的資料暫時不要動，如下。
然後在Startup.cs檔案ConfigureServices方法的中介軟體services.AddSwaggerGen下面新增如下語句，上面如果新增過了的可以忽略。
//顯示每個方法的註釋和方法引數的註釋 // 獲取xml檔名 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; // 獲取xml檔案路徑 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); // 新增控制器層註釋，true表示顯示控制器註釋 c.IncludeXmlComments(xmlPath, true);
6. swagger展示
到這裡我們就完成配置了，接下來我們執行專案看一下效果。
這裡訪問的話是我預設的地址：https://localhost:44383/weatherforecast，我們需要把後面的weatherforecast更換為swagger/index.html，如下
訪問地址：http://localhost:54848/swagger/index.html
很顯然我們swagger搭建成功了，接下來我們訪問看看效果怎麼樣。
7. swagger如何除錯介面
我們可以看到我們的所有介面，然後找到需要除錯的介面除錯就可以了，我們除錯一下帶引數的。
1、點選需要除錯的介面地址；
2、點選Try it out，這時會變成Cancel，點選Cancel會回到Try it out（Cancel狀態是可以讀寫狀態，Try it out是隻讀狀態）；
3、在輸入框輸入內容後，點選Execute進行介面請求。
4、點選請求後，Server response位置就是介面返回的的資料了。
這樣我們就完成了swagger的簡單操作啦。
總結
對於swagger的應用遠遠不止於此，但是常規的操作已經夠我們日常開發中使用了，具體問題具體分析，需要擴充時在進行新增即可。
其實不管是使用Fiddler、PostMan、JMeter、SoupUI等 還是swagger，我們不用盲目跟風，選擇自己用起來最熟練的使用即可。
工具嘛，選擇一個自己能熟練使用就挺好了，當然，能瞭解更多也沒壞處。
喜歡就點贊加關注。
歡迎關注訂閱微信公眾號【熊澤有話說】，更多好玩易學知識等你來取
作者：熊澤-學習中的苦與樂
公眾號：熊澤有話說
QQ群：711838388
出處：https://www.cnblogs.com/xiongze520/p/16478329.html
您可以隨意轉載、摘錄，但請在文章內註明作者和原文連結。
