如何在SwaggerUI（Swashbuckle）中友好展示REST API的SearchType可选值？

嘿，我完全懂你想让SwaggerUI里的可选值展示得更直观的需求——只靠XML注释确实不够友好，用户得自己去翻注释，还容易输错。下面有几个比单纯写注释好用多的实现方式，你可以根据自己的场景选：

1. 首选：把SearchType改成C#枚举类型 #

这是最省心的方案，不仅能让SwaggerUI自动展示下拉可选列表，还能在代码层面限制输入的合法性，避免无效值。

先定义枚举：

public enum SearchType
{
    InFoo,
    NotInFoo,
    AllExceptFoo
}

然后更新你的模型：

public class SearchItem
{
    public string Text { get; set; }
    public SearchType SearchType { get; set; }
}

public class SearchRequest
{
    public List<SearchItem> Searchs { get; set; }
}

做完这步，SwaggerUI里的SearchType字段会直接变成下拉选择框，把三个可选值列出来，用户不用手动输入，还能杜绝拼写错误。

2. 兼容字符串类型：用EnumDataType注解+Swashbuckle扩展 #

如果因为历史兼容或者其他原因必须保留SearchType为string类型，那可以用[EnumDataType]注解配合自定义SchemaFilter，让SwaggerUI识别出可选值。

首先还是定义枚举（用来约束可选值）：

public enum SearchTypeEnum
{
    InFoo,
    NotInFoo,
    AllExceptFoo
}

然后给模型字段加注解：

public class SearchItem
{
    public string Text { get; set; }
    
    [EnumDataType(typeof(SearchTypeEnum))]
    public string SearchType { get; set; }
}

接下来在Swashbuckle的配置里加一个自定义SchemaFilter，让它解析这个注解：

// 在Program.cs或Startup.cs的AddSwaggerGen里添加
builder.Services.AddSwaggerGen(c =>
{
    // 其他配置...
    c.SchemaFilter<EnumDataTypeSchemaFilter>();
});

// 自定义的SchemaFilter类
public class EnumDataTypeSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        var enumAttr = context.MemberInfo?.GetCustomAttribute<EnumDataTypeAttribute>();
        if (enumAttr != null && enumAttr.EnumType.IsEnum)
        {
            schema.Type = "string";
            schema.Enum = Enum.GetNames(enumAttr.EnumType)
                .Select(name => new OpenApiString(name))
                .Cast<IOpenApiAny>()
                .ToList();
        }
    }
}

这样SwaggerUI里的SearchType字段会显示允许的字符串值列表，同时保持字段类型为string。

3. 快速方案：直接用SwaggerSchema注解指定允许值 #

如果场景很简单，不想搞枚举或者过滤器，也可以直接用[SwaggerSchema]注解硬编码允许的值：

public class SearchItem
{
    public string Text { get; set; }
    
    [SwaggerSchema(AllowedValues = new[] { "InFoo", "NotInFoo", "AllExceptFoo" })]
    public string SearchType { get; set; }
}

这种方式最直接，不用额外配置，但缺点是如果后续可选值有变更，你得手动修改代码里的数组，维护起来不如枚举方便。

内容的提问来源于stack exchange，提问作者Mr Giggles