前言

    从Swagger2.0升级到Swagger3.0,发现枚举类型的注释不显示了。上网多方搜寻以后,发现好像没有官方的办法去解决,只能通过自身写适配Swagger的Filter去自行处理。

解决方法

    方案大致通过以下几步来完成Filter

  • 1、获取Model层所有枚举
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    /// <summary>
    /// 获取Model层所有枚举
    /// </summary>
    /// <returns></returns>
    private static Dictionary<string, Type> GetAllEnum()
    {
    var types = Assembly.Load("xxx.Models").GetTypes();
    var dic = new Dictionary<string, Type>();
    foreach (var item in types)
    {
    if (!item.IsEnum) continue;
    if (!dic.ContainsKey(item.Name))
    {
    dic.Add(item.Name, item);
    }
    }
    return dic;
    }
  • 2、处理获取到的枚举
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    /// <summary>
    /// 处理枚举
    /// </summary>
    /// <param name="type"></param>
    /// <param name="enums"></param>
    /// <returns></returns>
    private static string DescribeEnum(Type type, List<OpenApiLong> enums)
    {
    var enumDescriptions = new List<string>();
    foreach (var item in enums)
    {
    if (type == null) continue;
    var value = Enum.Parse(type, item.Value.ToString());
    var desc = GetDescription(type, value);
    enumDescriptions.Add(string.IsNullOrEmpty(desc) ? $"{item.Value}": $"{item.Value} - {desc}");
    }
    return $"<br/>{Environment.NewLine}{string.Join("<br/>" + Environment.NewLine, enumDescriptions)}";
    }
  • 3、处理过程中获取枚举的描述值
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    /// <summary>
    /// 获取描述值
    /// </summary>
    private static string GetDescription(Type t, object value)
    {
    foreach (var info in t.GetMembers())
    {
    if (info.Name == t.GetEnumName(value))
    {
    foreach (var attr in Attribute.GetCustomAttributes(info))
    {
    if (attr.GetType() == typeof(DescriptionAttribute))
    {
    return ((DescriptionAttribute)attr).Description;
    }
    }
    }
    }
    return string.Empty;
    }
  • 4、继承Swashbuckle.AspNetCore.SwaggerGen下的IDocumentFilter
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    public class EnumFilter : IDocumentFilter
    {
    public void Apply(Microsoft.OpenApi.Models.OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
    var dic = GetAllEnum();
    foreach (var item in swaggerDoc.Components.Schemas)
    {
    var property = item.Value;
    var typeName = item.Key;
    if (property.Enum != null &amp;&amp; property.Enum.Count > 0)
    {
    var itemType = dic.ContainsKey(typeName) ? dic[typeName] : null;
    var list = new List<OpenApiLong>();
    foreach (var val in property.Enum)
    {
    long value;
    if (property.Format == "int32")
    {
    value = Convert.ToInt64(((OpenApiInteger)val).Value);
    }
    else
    {
    value = Convert.ToInt64(((OpenApiLong)val).Value);
    }
    list.Add(new OpenApiLong(value));
    }
    property.Description = DescribeEnum(itemType, list);
    }
    }
    }
    }
  • 5、注入Swagger的时候加进去
    1
    2
    3
    4
    services.AddSwaggerGen(c =>{    
    // 通过Filter显示枚举描述
    c.DocumentFilter<EnumFilter>();
    });
        最终只要通过在枚举上打上 [Description(“”)] 特性,就会得到各个枚举的注释。
        具体效果如下:
    image
    image