參考地址，官網：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=visual-studio
與https://www.jianshu.com/p/349e130e40d5
當一個WebApi完成之后，書寫API檔案是一件非常頭疼的事，因為不僅要寫得清楚，能讓呼叫介面的人看懂，又是非常耗時耗力的一件事，在之前的一篇隨筆中（https://www.cnblogs.com/taotaozhuanyong/p/11567017.html），記載.Net Framework中WebApi生成檔案的時候，通過訪問指定的路徑，就可以獲取到Api檔案，在.NET Core中又怎么生成API檔案呢？使用Swagger，
為什么使用Swagger作為REST APIs檔案成功工具呢？
1、Swagger可以生產一個具有互動性的API控制臺，開發者可以用來學習和嘗試API，
2、Swagger可以生產客戶端SDK代碼用于各種不同的平臺上的實作，
3、Swagger檔案可以在許多不同的平臺上從代碼注釋中自動生成，
4、Swagger有一個強大的社區，里面有許多強悍的貢獻者，
Swagger簡單介紹
Swagger官網：https://swagger.io/irc/
Swagger Codegen：通過Codegen可將描述檔案生成html和cwiki形式的介面檔案，同時也能生成多種語言的服務端和客戶端的代碼，可以在后面的Swagger Editor中在線生成，
Swagger UI：提供了一個可視化的UI頁面 展示描述檔案，介面的呼叫方、測驗、專案經理等都可以在該頁面中對相關介面進行查閱和做一些簡單的介面請求，該專案支持在線匯入檔案和本地部署UI專案，
Swagger Editor：類似于markendown編輯器的編輯Swagger描述檔案的編輯器，改編輯器支持實時預覽描述檔案的更新效果，也提供了在線編輯器和本地部署編輯器兩種方式，
Swagger Inspector：感覺和postman差不多，是一個可以對介面進行測驗的在線版的postman，比在Swagger UI里面做介面請求，會回傳更多的資訊，也會保存你請求的實際請求引數等資料，
Swagger Hub：繼承了上面所有專案的各個功能，你可以以專案和版本為單位，將你的描述檔案上傳到Swagger Hub中，在Swagger Hub中跨域完成上面專案的所有作業，需要注冊賬號，分免費版和收費版，
下面介紹如何在ASP.NET Core中使用Swagger生成API說明檔案
.NET Core3.0已經出來了，那我們就基于.NET Core3.0新建一個WebApi專案吧，
這里為了演示Swagger的使用，就不創建空專案了，選擇ASP.NET Core 3.0
創建完成會顯示這個樣子，會給我們默認增加一個WeatherForecastController
[ApiController] [Route("[controller]")] public class WeatherForecastController : ControllerBase { private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; private readonly ILogger<WeatherForecastController> _logger; public WeatherForecastController(ILogger<WeatherForecastController> logger) { _logger = logger; } [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(); } }View Code
當我們這個時候運行的時候，會出現404的錯誤（不知道你們有沒有遇到，反正我是遇到了），不要著急，我們做以下修改就行，
首先在Controller中將[Route("[controller]")]====》[Route("api/WeatherForecast")]
再在launchSettings.json中做修改，
這樣，我們再訪問一下，就成功了，
回歸今天的主題，如何使用Swagger，
首先，安裝依賴包 Swashbuckle.AspNetCore，選擇最新版本的，使用Nuget或者控制臺都可以，.Net Core2.0下，這樣是沒問題的，但是在.Net Core3.0下，最好使用PowerShell進行安裝，
Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc2
添加并配置Swagger中間件
引入命名空間
using Swashbuckle.AspNetCore.Swagger;
在 Startup 類中，匯入以下命名空間來使用 OpenApiInfo 類：
using Microsoft.OpenApi.Models;
將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中：
在.Net Core3.0之前：
//注冊Swagger生成器，定義一個和多個Swagger 檔案 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" }); });
但是在.Net Core 3.0中，要這樣寫
services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); });
一個是new Info(),一個是new OpenApiInfo()，這也是為什么最好使用Powershell去安裝參考，否則會報錯：
TypeLoadException: Could not load type 'Microsoft.AspNetCore.Mvc.MvcJsonOptions' from assembly 'Microsoft.AspNetCore.Mvc.Formatters.Json, Version=3.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'.
在Configure方法中，啟動中間件為生成的JSON檔案和Swagger UI提供服務：
//啟用中間件服務生成Swagger作為JSON終結點 app.UseSwagger(); //啟用中間件服務對swagger-ui，指定Swagger JSON終結點 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); });
啟動應用，并導航到http://localhost:<post>/swagger/v1/swagger.sjon，生成的描述終結點的檔案顯示如下：
可在 http://localhost:<port>/swagger 找到 Swagger UI， 通過 Swagger UI 瀏覽 API檔案，如下所示，
要在應用的根 (http://localhost:<port>/) 處提供 Swagger UI，請將 RoutePrefix 屬性設定為空字串：
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
c.RoutePrefix = string.Empty;
});
自定義和擴展：
Swagger提供了為物件模型進行歸檔和自定義UI以匹配你的主題的選項，
API資訊說明
傳遞給AddSwagger方法的配置操作會添加注入作者、許可證和說明資訊：在.Net Core3.0是這樣寫的，與之前寫法稍微有點區別，請注意下，
services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "Bingle API", Description = "一個簡單的ASP.NET Core Web API", TermsOfService = new Uri("https://www.cnblogs.com/taotaozhuanyong"), Contact = new OpenApiContact { Name = "bingle", Email = string.Empty, Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"), }, License = new OpenApiLicense { Name = "許可證", Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"), } }); });
訪問地址http://localhost:<port>/swagger，就看到上述添加的資訊
上述完成之后，我們發現，介面并沒有注釋，那么我們怎么來添加注釋呢？
XML注釋
在Visual Studio中，在“解決方案資源管理器”中右鍵單擊該專案，然后選擇“編輯 <project_name>.csproj” ，手動將突出顯示的行添加到 .csproj 檔案 ：
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>
啟用 XML 注釋，為未記錄的公共型別和成員提供除錯資訊， 警告訊息指示未記錄的型別和成員， 例如，以下訊息指示違反警告代碼 1591：
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'
要在專案范圍內取消警告，請定義要在專案檔案中忽略的以分號分隔的警告代碼串列， 將警告代碼追加到 $(NoWarn);
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>
services.AddSwaggerGen修改為如下：
注意：
1、對于Linux或者非Windows作業系統，檔案名和路徑區分大小寫，例如“MyWebApiUseSwagger.xml”檔案在Windows上有效，但在CentOS上無效
2、獲取應用程式路徑，建議采用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取
services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "Bingle API", Description = "一個簡單的ASP.NET Core Web API", TermsOfService = new Uri("https://www.cnblogs.com/taotaozhuanyong"), Contact = new OpenApiContact { Name = "bingle", Email = string.Empty, Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"), }, License = new OpenApiLicense { Name = "許可證", Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"), } }); //為 Swagger JSON and UI設定xml檔案注釋路徑 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath); });
經過上面的配置，介面中的方法就有注釋了：
通過上面的操作就可以總結出來，Swagger UI顯示上述注釋代碼 <summary>元素的內部文本作為api大的注釋！當然你還可以將 remarks 元素添加到 Get 操作方法檔案， 它可以補充 <summary> 元素中指定的資訊，并提供更可靠的 Swagger UI， <remarks> 元素內容可包含文本、JSON 或 XML， 代碼如下：
/// <summary> /// 這是一個帶引數的get請求 /// </summary> /// <remarks> /// 例子: /// Get api/Values/1 /// </remarks> /// <param name="id">主鍵</param> /// <returns>測驗字串</returns> [HttpGet("{id}")] public ActionResult<string> Get(int id) { return $"你請求的id是{id}"; }
可以看到如下效果：
描述回應型別
使用WebApi的開發人員最關心的問題是回傳的內容，特別是回應型別和錯誤代碼，在XML注釋和資料中表示相應型別的錯誤代碼，Get 操作成功后回傳HTTP 201狀態碼，發布的請求正文為NULL，將回傳HTTP 400狀態代碼，如果Swagger UI中沒有提供合適的檔案，那么使用者會缺少對這些預期的結果的了解，
在以下的實體中，通過突出的行解決此問題：
/// <summary> /// 這是一個帶引數的get請求 /// </summary> /// <remarks> /// 例子: /// Get api/Values/1 /// </remarks> /// <param name="id">主鍵</param> /// <returns>測驗字串</returns> /// <response code="201">回傳value字串</response> /// <response code="400">如果id為空</response> // GET api/values/2 [HttpGet("{id}")] [ProducesResponseType(201)] [ProducesResponseType(400)] public ActionResult<string> Get(int id) { return $"你請求的id是{id}"; }
以下是看到的效果
如何使用Swagger UI進行測驗？
點擊Try it out
輸入引數，再點擊Excute：
得到的回應結果：
以上便是在.Net Core 3.0 WebApi中使用Swagger的基本介紹，以及在.Net Core3.0下如何創建WebApi，在使用Swagger在和以前有什么區別的的介紹，希望能夠幫助到大家，
轉載請註明出處，本文鏈接：https://www.uj5u.com/net/114324.html
標籤：.NET Core
上一篇：asp.net core IdentityServer4 實作 resource owner password credentials(密碼憑證)