如何在Swagger中为枚举类添加文档注释？

我正在使用Swagger生成API文档，希望为枚举添加描述信息，目前通过自定义过滤器利用特性提取类和枚举的信息，示例如下：

using System.ComponentModel;
...
[DisplayName("Upload class")]            // 可正常使用
public class Upload
{
    [DisplayName("Primary Key")]          // 可正常使用
    public int UploadMetaId { get; set; }
    [Display(Name = "document name")]     // 也可正常使用
    public string Title { get; set; }
}

但在枚举类上遇到问题：

[DisplayName("Document types")]    // 非法，触发CS0592错误
// 或
[Display(Name = "Document types")]  // 同样非法，触发CS0592错误
public enum UploadType
{
    [Display(Name = "Årsopgørelse")] // 可正常使用
    PartnerAarsopgoerelse = 1,
    [Display(Name = "Ægtefælles årsopgørelse")]
    AegtefaelleAarsopgoerelse = 2
}

错误CS0592提示该特性不适用于此声明类型。请问可用什么特性替代？

更新：我使用的NuGet包版本如下：

• Microsoft.OpenApi (1.6.15)
• Swashbuckle.AspNetCore(6.6.2)

解决方案 #

1. 使用[Description]特性（来自System.ComponentModel） #

[DisplayName]和[Display]特性默认不支持枚举类级别，而[Description]特性可以直接应用在枚举类上，示例：

using System.ComponentModel;

[Description("Document types")]
public enum UploadType
{
    [Display(Name = "Årsopgørelse")]
    PartnerAarsopgoerelse = 1,
    [Display(Name = "Ægtefælles årsopgørelse")]
    AegtefaelleAarsopgoerelse = 2
}

之后在自定义过滤器中，针对枚举类型提取DescriptionAttribute的Description属性值即可。

2. 自定义支持枚举类的特性 #

如果需要更定制化的逻辑，可以自行定义特性，指定其适用目标包含枚举：

using System;

[AttributeUsage(AttributeTargets.Enum | AttributeTargets.Field | AttributeTargets.Class | AttributeTargets.Property, AllowMultiple = false)]
public class ApiDisplayAttribute : Attribute
{
    public string Name { get; set; }

    public ApiDisplayAttribute(string name)
    {
        Name = name;
    }
}

使用示例：

[ApiDisplay("Document types")]
public enum UploadType
{
    [ApiDisplay("Årsopgørelse")]
    PartnerAarsopgoerelse = 1,
    [ApiDisplay("Ægtefælles årsopgørelse")]
    AegtefaelleAarsopgoerelse = 2
}

随后在自定义过滤器中统一提取该特性的Name值即可。

3. 利用Swashbuckle的SchemaFilter扩展配置 #

如果不想修改现有特性，可通过SchemaFilter直接为枚举类添加描述：

public class EnumSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type.IsEnum)
        {
            // 方式1：针对特定枚举直接设置描述
            if (context.Type == typeof(UploadType))
            {
                schema.Description = "Document types";
            }
            
            // 方式2：通过反射读取[Description]特性值（推荐）
            var descriptionAttr = context.Type.GetCustomAttributes(typeof(DescriptionAttribute), false).FirstOrDefault() as DescriptionAttribute;
            if (descriptionAttr != null)
            {
                schema.Description = descriptionAttr.Description;
            }
        }
    }
}

最后在Startup/Program中注册该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<EnumSchemaFilter>();
});

内容的提问来源于stack exchange，提问作者Anders Finn Jørgensen