ASP.NET Core中如何修改Swagger UI里可空枚举属性的示例值？

问题根源 #

你当前代码通过Zip按排序后的顺序匹配模型属性与Swagger Schema属性，这种方式依赖两者排序完全一致，但Swagger默认会将属性名转为驼峰式，而C#模型属性是帕斯卡命名，大小写差异可能导致排序后的顺序不匹配，进而使可空枚举属性未被正确处理。此外，可空枚举的Schema默认可能未标记为可空，也会影响示例值的显示。

修改后的代码 #

public class SwaggerPropertyValueFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type.Namespace == "MyAPI.Services.Models" && context.Type.GetConstructor(Type.EmptyTypes) != null)
        {
            var modelProps = context.Type.GetProperties();
            
            foreach(var modelProp in modelProps)
            {
                // 将帕斯卡命名的属性名转为驼峰式，匹配Swagger生成的属性名
                var camelCasePropName = char.ToLowerInvariant(modelProp.Name[0]) + modelProp.Name.Substring(1);
                
                if (schema.Properties.TryGetValue(camelCasePropName, out var schemaProp))
                {
                    var underlyingType = Nullable.GetUnderlyingType(modelProp.PropertyType);
                    if (underlyingType != null)
                    {
                        // 设置示例值为null
                        schemaProp.Example = new OpenApiNull();
                        // 标记Schema为可空
                        schemaProp.Nullable = true;
                    }
                }
            }
        }
    }
}

关键修改说明 #

• 精确匹配属性：不再依赖排序后的顺序匹配，而是将模型属性名转为驼峰式后，从Swagger Schema的属性集合中精确查找对应项，避免因大小写、排序差异导致的匹配错误。
• 强制标记可空：显式设置schemaProp.Nullable = true，确保Swagger UI正确识别该属性为可空类型，配合OpenApiNull示例值，能正确在UI中展示null示例。
• 简化逻辑：直接遍历模型属性并匹配对应Schema，代码更直观可靠。

额外提示 #

如果使用的是较新版本的Swashbuckle.AspNetCore（v5.x及以上），可以检查是否启用了SupportNonNullableReferenceTypes配置，该配置会影响可空类型的Schema生成，确保其与你的需求一致。

内容的提问来源于stack exchange，提问作者Kevin Krumwiede