什麼是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
您可以隨意轉載、摘錄，但請在文章內註明作者和原文鏈接。
