Asp.Net Core Swagger 接口分組(支持接口一對多暴露)

開始之前，先介紹下swagger常用方法。

services.AddSwaggerGen    //添加swagger中間件

c.SwaggerDoc  //配置swagger文檔，也就是右上角的下拉框內容

 

c.IncludeXmlComments  //引用程序集xml，用於加載出 備注信息等如圖

 

 

c.AddSecurityDefinition  //添加授權驗證

 

 

 c.DocInclusionPredicate    //核心方法，指定分組被加載時 回調進入，也就是swagger右上角下拉框內的分組加載時

每一個分組加載時都會遍歷所有控制器的action 進入一次這個方法體內，返回true則 暴露 否則隱藏

                    c.DocInclusionPredicate((docName, apiDescription) =>
                    {
                          //docName分組 的apiDescription 方法是否暴露
                          //return true 暴露 反之 隱藏
                          return true;
                    });

多分組步驟：

1.定義自定義標簽

    public class ApiGroupAttribute : Attribute
    {
        public ApiGroupAttribute(params ApiGroupNames[] name)
        {
            GroupName =  name;
        }

        public ApiGroupNames[] GroupName { get; set; }

    }

    public enum ApiGroupNames
    {
        [GroupInfo(Title = "登錄接口", Description = "用於登錄", Version = "20200828")]
        Login,
    }

    public class GroupInfoAttribute : Attribute
    {
        public string Title { get; set; }
        public string Version { get; set; }
        public string Description { get; set; }
    }

2.將標簽放在需要 分組的控制器或方法上

//可加載多個標簽，用於1個接口對應多個分組
[ApiGroup(ApiGroupNames.Login,ApiGroupNames.SubmitProgram)]

3.利用枚舉反射加載出每個分組的Doc

services.AddSwaggerGen(c =>
                {                  
                    //遍歷ApiGroupNames所有枚舉值生成接口文檔，Skip(1)是因為Enum第一個FieldInfo是內置的一個Int值  
typeof(ApiGroupNames).GetFields().Skip(1).ToList().ForEach(f =>
                    {
                        //獲取枚舉值上的特性
                        if (SwaggerEnumNames.Count(x => x.ToLower() == f.Name.ToLower()) > 0)
                        {
                            var info = f.GetCustomAttributes(typeof(GroupInfoAttribute), false).OfType<GroupInfoAttribute>().FirstOrDefault();
                            c.SwaggerDoc(f.Name, new Microsoft.OpenApi.Models.OpenApiInfo
                            {
                                Title = info?.Title,
                                Version = info?.Version,
                                Description = info?.Description
                            });
                        }
                    });
}

4.DocInclusionPredicate 內寫核心邏輯代碼，利用反射的類進行判斷標簽值

                    //判斷接口歸於哪個分組
                    c.DocInclusionPredicate((docName, apiDescription) =>
                    {
                                //反射拿到值
                                var actionlist = apiDescription.ActionDescriptor.EndpointMetadata.Where(x => x is ApiGroupAttribute);
                                if (actionlist.Count() > 0)
                                {
                                    //判斷是否包含這個分組
                                    var actionfilter = actionlist.FirstOrDefault() as ApiGroupAttribute;
                                    return actionfilter.GroupName.Count(x => x.ToString() == docName) > 0;
                                }
                            return false;
                        }
                    });

 

如需要全部接口暴露並不用打標簽的，用SwaggerDoc單獨加載一個Doc用於顯示全部接口，在DocInclusionPredicate內加入 判斷 如果docName等於全部接口的DocName那么直接return true即可，可靈活運行，可配置在json 也可配置在數據庫等地方。用於指定分組是否暴露。以上加載Doc時， SwaggerEnumNames 就是需要暴露的分組列表，需要的自己定義來源

 

本文章參考 https://www.cnblogs.com/caijt/p/10739841.html 改寫的 一對多分組模式。需要一對一的可以參考