【我的學習】: Swagger的配置及使用

1、什麼是Swagger?爲何要使用Swagger?

　　Swagger 是一個規範和完整的框架，如今愈來愈多的項目採用先後端分離，API成了後端與前端溝通的紐帶，API的文檔也變得愈來愈重要。使得這個集文檔在線自動生成+美觀+測試於一身的框架Swagger愈來愈受歡迎。

　　咱們以前經過Word、Excel手動編寫的接口文檔或者說是第三方的api文檔管理工具（小幺雞等），你們有沒有遇到如下狀況：

• 前端常常抱怨後端給的接口文檔與實際狀況不一致；
• 後端以爲編寫及維護接口文檔會耗費很多精力，常常來不及或忘記更新；

　　Swagger完美（這就跟開發平常的開發習慣息息相關了，要及時更新代碼註釋）解決了以上的問題，Swagger在API開發新版本或者迭代版本的時候，只須要更新Swagger描述文件，就能夠自動生成接口文檔和客戶端服務端代碼，作到調用端代碼、服務端代碼以及接口文檔的一致性；

2、引用和配置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

3、爲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)]

4、版本控制

　　說到版本控制，咱們第一時間想到的是Git、SVN等的源代碼版本管理器，版本控制，顧名思義，就是對程序代碼，文件等的變動管理，多個版本保證代碼更改後有跡可循，可實時恢復以前版本；這就是項目的版本控制，而咱們今天說的是對API的版本控制，下面咱們藉助swagger實現對api的版本控制。

1. 首先先建一個用於區分版本的枚舉類以下：

   namespace Study.NetCore.SwaggerHelper { /// <summary>
       /// 版本控制 /// </summary>
       public class VersionControl { /// <summary>
           /// 接口版本號 /// </summary> 
           public enum ApiVersion { /// <summary>
               /// v1版本 /// </summary>
               v1 = 1, /// <summary>
               /// v2版本 /// </summary>
               v2 = 2, } } }

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

3. 接着，找到配置啓動項的方法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

4. 運行以下（藉助Swagger來實現對API多版本的展現）以下：
5. 自定義路由，新建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(); } } }

6. 接口版本控制的使用

• • 對要區分版本的接口添加特性如:

    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 文件夾下，新建兩個文件夾， v一、v2，而後添加相同的接口控制器，自定義便可，以下：
  • 運行，切換swaggerUI 版本查看。