一、什么是Swagger?為什么要使用Swagger?
Swagger 是一個規范和完整的框架，現在越來越多的項目采用前后端分離，API成了后端與前端溝通的紐帶，API的文檔也變得越來越重要。使得這個集文檔在線自動生成+美觀+測試於一身的框架Swagger越來越受歡迎。
我們之前通過Word、Excel手動編寫的接口文檔或者說是第三方的api文檔管理工具（小幺雞等），大家有沒有遇到以下情況：
- 前端經常抱怨后端給的接口文檔與實際情況不一致；
- 后端覺得編寫及維護接口文檔會耗費不少精力，經常來不及或忘記更新；
Swagger完美（這就跟開發日常的開發習慣息息相關了，要及時更新代碼注釋）解決了以上的問題，Swagger在API開發新版本或者迭代版本的時候，只需要更新Swagger描述文件，就可以自動生成接口文檔和客戶端服務端代碼，做到調用端代碼、服務端代碼以及接口文檔的一致性；
二、引用和配置Swagger
- 通過工具-->NutGet包管理器-->程序包管理器控制台添加Swagger插件 shell命令如下：install-package Swashbuckle.AspNetCore -version 4.0.1 -Study.NetCore
- 打開項目的NetCore項目的Startup.cs類（程序入口）配置Swagger，如下：
#region Swagger配置 services.AddSwaggerGen(swg => { swg.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Version = "v1", Title = "Study.NetCore API", Description = "API-說明文檔", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Study.NetCore", Email = "", Url = "" } }); }); #endregion
- 在Configure類中啟動Swagger中間件，如下：
#region 啟動Swagger app.UseSwagger(); app.UseSwaggerUI(swg => { swg.SwaggerEndpoint("/swagger/v1/swagger.json", "APIExplainDoc"); }); #endregion
- 啟動項目，我們可以看到頁面直接進入了如下的頁面：
- 我們輸入/Swagger可以正常進入SwaggerUI頁面，接下來我們把默認路由指向SwaggerUI頁面。打開launchSettings.json修改如下：
- 這樣我們運行Swagger項目，默認打開的就是SwaggerUI頁面；
- 如果要發布到正式環境，就會發現，上邊的那種默認啟動首頁無效了，還是需要我們每次手動在域名后邊輸入 /swagger，這時我們在Configure中配置swg.RoutePrefix =“” 如下：
#region 啟動Swagger app.UseSwagger(); app.UseSwaggerUI(swg => { swg.SwaggerEndpoint("/swagger/v1/swagger.json", "APIExplainDoc"); swg.RoutePrefix = ""; }); #endregion
三、為SwaggerUI接口添加注釋
- 右鍵項目名稱-->屬性-->生成-->勾選XML文檔文件，勾選XML文檔文件之后，通過修改ConfigureServices讓項目啟動時讀取這個Xml文件，如下：
#region Swagger配置 services.AddSwaggerGen(swg => { swg.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Version = "v1", Title = "Study.NetCore API", Description = "API-說明文檔", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Study.NetCore", Email = "", Url = "" } }); var bashPath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(bashPath, "Study.NetCore.xml"); swg.IncludeXmlComments(xmlPath, true);//這個是controller的注釋 }); #endregion
- 這樣運行項目后，注釋都有了，非常完美。如下：
添加實體類的說明：基本和api的配置一致，首先勾選XML文檔文件，然后在ConfigureServices中修改swagger配置，如下：
#region Swagger配置 services.AddSwaggerGen(swg => { swg.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Version = "v1", Title = "Study.NetCore API", Description = "API-說明文檔", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Study.NetCore", Email = "", Url = "" } }); var bashPath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(bashPath, "Study.NetCore.xml"); swg.IncludeXmlComments(xmlPath, true);//這個是controller的注釋 //model的Xml文件 var xmlModelPath = Path.Combine(bashPath, "Study.NetCore.Model.xml"); swg.IncludeXmlComments(xmlModelPath); }); #endregion
- 如果要隱藏某個接口，直接在action或controller上添加特性
[ApiExplorerSettings(IgnoreApi = true)]
四、版本控制
說到版本控制，我們第一時間想到的是Git、SVN等的源代碼版本管理器，版本控制，顧名思義，就是對程序代碼，文件等的變更管理，多個版本保證代碼更改后有跡可循，可實時恢復之前版本；這就是項目的版本控制，而我們今天說的是對API的版本控制，下面我們借助swagger實現對api的版本控制。
- 首先先建一個用於區分版本的枚舉類如下：
namespace Study.NetCore.SwaggerHelper { /// <summary> /// 版本控制 /// </summary> public class VersionControl { /// <summary> /// 接口版本號 /// </summary> public enum ApiVersion { /// <summary> /// v1版本 /// </summary> v1 = 1, /// <summary> /// v2版本 /// </summary> v2 = 2, } } }
- 接下來，我們打開StartUp.cs類，在ConfigureServices配置中心，修改Swagger的配置如下：
private const string apiName = "Study.NetCore";
#region Swagger配置 var bashPath = PlatformServices.Default.Application.ApplicationBasePath; services.AddSwaggerGen(swg => { //遍歷版本號展示 typeof(ApiVersion).GetEnumNames().ToList().ForEach(version => { swg.SwaggerDoc(version, new Swashbuckle.AspNetCore.Swagger.Info { Version = version, Title = $"{apiName} API", Description = $"{apiName} API" + version, TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = $"{apiName}", Email = "", Url = "" } }); }); var xmlPath = Path.Combine(bashPath, "Study.NetCore.xml"); swg.IncludeXmlComments(xmlPath, true);//這個是controller的注釋 var xmlModelPath = Path.Combine(bashPath, "Study.NetCore.Model.xml");//model的Xml文件 swg.IncludeXmlComments(xmlModelPath); }); #endregion - 接着，找到配置啟動項的方法configure，修改Swagger啟動代碼如下：
#region 啟動Swagger app.UseSwagger(); /* * 之前只有一個版本，所以固定寫死 * 遍歷接口版本，並倒敘展示 */ app.UseSwaggerUI(swg => { typeof(ApiVersion).GetEnumNames().OrderByDescending(ver => ver).ToList().ForEach(version => { swg.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"StudyNetCore API {version}"); swg.RoutePrefix = ""; }); }); #endregion
- 運行如下（借助Swagger來實現對API多版本的展示）如下：
- 自定義路由，新建ApiRouteAttribute特性類，如下：
namespace Study.NetCore.SwaggerHelper { /// <summary> /// 自定義路由 /api/{version}/[controler]/[action] /// </summary> [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class ApiRouteAttribute : RouteAttribute, IApiDescriptionGroupNameProvider { /// <summary> /// 分組名稱,是來實現接口 IApiDescriptionGroupNameProvider /// </summary> public string GroupName { get; set; } /// <summary> /// 自定義路由構造函數，繼承基類路由 /// </summary> /// <param name="actionName"></param> public ApiRouteAttribute(string actionName = "[action]") : base("/api/{version}/[controller]/" + actionName) { } ///// <summary> /// 自定義版本+路由構造函數，繼承基類路由 /// </summary> /// <param name="actionName"></param> /// <param name="version"></param> public ApiRouteAttribute(ApiVersion version, string actionName = "") : base($"/api/{version.ToString()}/[controller]/{actionName}") { GroupName = version.ToString(); } } }
- 接口版本控制的使用
-
- 對要區分版本的接口添加特性如:
namespace Study.NetCore.Controllers { [Route("api/[controller]")] [ApiController] public class ValuesController : ControllerBase { /// <summary> /// 測試注釋有沒有加上1 /// </summary> /// <returns></returns> [HttpGet] public ActionResult<IEnumerable<string>> Get() { return new string[] { "value1", "value2" }; } [HttpGet] //和上邊的版本控制以及路由地址都是一樣的 [ApiRouteAttribute(ApiVersion.v2, "TestV2")] public string TestV2() { return "我是老二"; } [HttpGet("Test")] public string Test() { return "我是老大"; } } }
- 對要區分同名的接口：在 controller 文件夾下，新建兩個文件夾， v1、v2，然后添加相同的接口控制器，自定義即可，如下：
- 運行，切換swaggerUI 版本查看。
- 對要區分版本的接口添加特性如: