Asp.NET Core 7.0 Minimal API：为DateOnly指定正确的OpenAPI类型

问题场景 #

你在Minimal API中定义了接收DateOnly类型的查询参数接口，但默认生成的Swagger Schema仅标记为string类型，缺少符合OpenAPI规范的format: "date"属性。尝试用WithOpenApi直接替换Schema对象未生效。

解决方案1：修改现有Schema实例（单接口处理） #

直接新建OpenApiSchema对象赋值会被Swagger的默认生成逻辑覆盖，正确做法是修改已存在的Schema实例的属性：

app.MapGet("/info", (DateOnly date) => $"Experimenting with APIs {date.ToString("yyyy-MM")}")
.WithOpenApi(o => {
    o.Summary = "Summary is added";
    var dateParam = o.Parameters[0];
    dateParam.Description = "Description is added";
    // 修改现有Schema的Format属性，而非新建对象
    dateParam.Schema.Format = "date";
    return o;
});

生成的Swagger JSON会包含预期的格式信息：

"parameters": [
{
  "name": "date",
  "in": "query",
  "description": "Description is added",
  "required": true,
  "style": "form",
  "schema": {
    "type": "string",
    "format": "date"
  }
}
]

解决方案2：全局配置（多接口统一处理） #

如果多个接口都用到DateOnly，可以通过全局Schema过滤器统一配置，避免重复修改：

1. 注册自定义Schema过滤器：

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

// 自定义Schema过滤器类
public class DateOnlySchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(DateOnly))
        {
            schema.Type = "string";
            schema.Format = "date";
        }
    }
}

2. 可选：添加JSON转换器优化参数解析体验
   为了让接口能正确解析前端传入的日期字符串，可配置DateOnly的JSON转换器：

builder.Services.Configure<JsonOptions>(options =>
{
    options.JsonSerializerOptions.Converters.Add(new DateOnlyJsonConverter());
});

// 自定义DateOnly JSON转换器
public class DateOnlyJsonConverter : 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, CultureInfo.InvariantCulture);
    }

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

原理说明 #

直接新建OpenApiSchema赋值未生效，是因为Swagger生成文档时，会先基于参数类型生成默认Schema，后续的默认处理逻辑会覆盖你新建的Schema对象。而修改现有Schema实例的属性，会保留你的修改并最终写入Swagger JSON。

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