6.swagger完善：界面顯示註釋+多版本控制

周末，寫點簡單的水一下。

新版本的vs創建項目的時候可以選擇自帶一個swagger。然而這隻是基本的swagger功能。

 幾個介面無所謂啦，隨著介面越來越多，就這麼丟給你，一時間也會懵逼，所以這篇文章要做的有兩個功能。

1. 給swagger文檔添加註釋
2. 給swagger添加切換“版本”的功能(也可以理解為：讓不同功能模塊的介面顯示在一個頁面，不然幾十上百的介面放一起找也不好找呀~)

右鍵項目>屬性>生成>輸出>XML文檔文件路徑，添加輸出的路徑，我一般會設置在程式集下的根路徑，例如這樣：

文件命名什麼的隨意，一般跟項目有關例如：FastEasy.Readme.xml。

然後去swagger相關的Module模塊中去添加一些配置。我這個文章相關的項目一開始的時候就將這些註入配置單獨搞成獨立的一個模塊，所以你只是看到這個文章，那預設就在Programs裡面找AddSwaggerGen就好。

        Services.AddSwaggerGen(s =>
        {
            //多版本
            typeof(SwaggerVersion).GetEnumNames().ToList().ForEach(v =>
            {
                s.SwaggerDoc(v, new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Version = v,
                    Description = $"{v} API",
                    Title = v,
                });
                //添加註釋
                var basePath=AppDomain.CurrentDomain.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "FastEasy.Readme.xml");
                s.IncludeXmlComments(xmlPath,true);
            });
        });

 如果不需要切換版本，那就關註添加註釋下麵三行代碼就好，獲取註釋文檔的路徑，然後添加到swagger中。

接下來就是多版本切換，上面的代碼已經是了，需要在意的地方是typeof里的SwaggerVersion。這是創建的一個枚舉，然後在枚舉中按需添加不同的版本切換，例如

        public enum SwaggerVersion
        {
            FastEasy = 1,
            OpenAPI = 2
        }

如果要使用多版本，中間件管道里也要改一下

        app.UseSwagger();
        app.UseSwaggerUI(s =>
        {
            typeof(SwaggerVersion).GetEnumNames().ToList().ForEach(v =>
            {
                s.SwaggerEndpoint($"swagger/{v}/swagger.json", $"{v}");
                s.RoutePrefix = string.Empty;
            });
        });

到這裡就已經完成90%了。最後一步就是給不同的方法或者控制器添加[ApiExplorerSettings(GroupName = "OpenAPI")]

        [HttpGet("MUL")]
        [ApiExplorerSettings(GroupName = "OpenAPI")]
        public int MUL(int i, int j)
        {
            return test.MUL(i, j);
        }

原本是加減乘除4個介面，現在就是FastEasy下兩個，OpenAPI下兩個(只是測試，跟名稱毫無關係)

 現在完成了99%了。如果像我這種小公司，沒有版本的區別，無非就是為了看著方便，因為功能模塊去區分開來。就像現在，查看文檔的時候可以根據分類找到相對應的介面，不至於一眼亂糟糟的。

但是實際上並未完成版本控制，因為你會發現，他們的請求路徑是差不多的。如果要完成真正的版本控制，有兩種方法，第一種簡單，路由上寫死了：/v1/xxxx   /v2/xxxxx……

第二種就是自定義路由特性：添加一個特性配置的類:SwaagerRouteAttribute。我直接貼代碼了，很簡單的幾行，代碼的註釋足以解釋清楚了

    public class SwaagerRouteAttribute : RouteAttribute, IApiDescriptionGroupNameProvider
    {
        /// <summary>
        /// 預設的路由配置
        /// </summary>
        /// <param name="actionName"></param>
        public SwaagerRouteAttribute(string actionName) : base(actionName)
        {
        }

        /// <summary>
        /// 分組名稱,控制不同版本:等同於配置ApiExplorerSettings(GroupName ="FastEasy")
        /// </summary>
        public string? GroupName { get; set; }

        /// <summary>
        /// 自定義的路由配置
        /// </summary>
        /// <param name="version"></param>
        /// <param name="actionName"></param>
        public SwaagerRouteAttribute(SwaggerVersion version, string actionName = "[action]") : base($"/{version.ToString()}/[controller]/{actionName}")
        {
            GroupName = version.ToString();
        }
    }

現在！用自己封裝的路由屬性添加到方法上面(截圖看的全)

此時才算完成真的版本控制效果：

 啊掰掰~