ASP.NET Core中Swagger显示DateOnly多余dayOfWeek字段的问题

为什么会显示多余的dayOfWeek字段？ #

Swagger（Swashbuckle）生成请求Schema时，是通过反射遍历目标类型的所有公共成员（包括只读属性）来构建结构的。DateOnly的DayOfWeek是一个公共只读属性，虽然它是通过日期计算得出的、不需要用户输入，但默认的Schema生成逻辑会把它包含进去，就出现了你看到的多余字段。

除了自定义类型之外的解决方法 #

方法1：添加Swagger Schema过滤器移除字段 #

创建一个自定义的Schema过滤器，在生成DateOnly的Schema时手动移除dayOfWeek属性：

public class RemoveDateOnlyDayOfWeekFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(DateOnly))
        {
            schema.Properties.Remove("dayOfWeek");
        }
    }
}

然后在Swagger注册时添加这个过滤器：

builder.Services.AddSwaggerGen(options =>
{
    options.SchemaFilter<RemoveDateOnlyDayOfWeekFilter>();
});

方法2：配置Json序列化忽略只读属性（谨慎使用） #

如果你的项目中不需要在任何序列化场景保留只读属性，可以在System.Text.Json的配置中开启忽略只读属性的设置，这样Swagger的Schema也会跟着排除这些属性：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.IgnoreReadOnlyProperties = true;
    });

注意：这个设置是全局的，会影响所有类型的序列化，如果你有其他需要保留的只读属性，不建议用这个方法。

方法3：使用自定义JsonConverter处理DateOnly #

编写一个自定义的JsonConverter<DateOnly>，只序列化/反序列化年、月、日三个字段，Swagger会根据这个转换器生成对应的Schema：

public class DateOnlyConverter : JsonConverter<DateOnly>
{
    private const string DateFormat = "yyyy-MM-dd";

    public override DateOnly Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateOnly.ParseExact(reader.GetString()!, DateFormat);
    }

    public override void Write(Utf8JsonWriter writer, DateOnly value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(DateFormat));
    }
}

然后注册这个转换器：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Converters.Add(new DateOnlyConverter());
    });

这种方法不仅能去掉Swagger里的dayOfWeek字段，还能让DateOnly以字符串格式（比如2024-05-20）在请求/响应中传输，更符合常见的API规范。

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