Swashbuckle.AspNetCore 中 DateOnly 类型在 Swagger UI 中的渲染问题解析

在 ASP.NET Core Web API 开发中，Swashbuckle.AspNetCore 是一个广泛使用的库，用于自动生成 API 文档和交互式 UI。近期，开发者在使用 DateOnly 类型时遇到了一个常见问题 - 该类型在 Swagger UI 中没有正确渲染为日期格式。

问题现象

当开发者在 ASP.NET 8 项目中使用 DateOnly 类型作为 API 参数或返回值时，Swagger UI 没有按照预期将其显示为标准的日期格式（如 "2024-03-06"）。相反，它被分解为多个属性，就像处理自定义复杂类型一样。这不仅影响了文档的可读性，还可能导致前端开发者误解 API 的数据格式要求。

问题根源

这个问题源于 Swashbuckle.AspNetCore 对 .NET 6 引入的 DateOnly 类型的默认处理方式。虽然 DateOnly 是 .NET 内置类型，但 Swashbuckle 没有自动将其映射为 OpenAPI 规范中的标准日期格式（type: string, format: date）。

解决方案

目前有两种主要解决方案：

1. 临时解决方案：手动映射 DateOnly 类型 开发者可以在 Swagger 配置中添加以下代码，明确指定 DateOnly 类型的映射方式：

builder.Services.AddSwaggerGen(options => {
    options.MapType<DateOnly>(() => new OpenApiSchema { 
        Type = "string",
        Format = "date" 
    });
});

2. 长期解决方案：等待官方修复 该问题已被识别为 bug，并在 Swashbuckle.AspNetCore 的后续版本中得到了修复。开发者可以关注项目更新，在修复版本发布后升级即可。

相关扩展

值得注意的是，类似的类型处理问题也可能出现在其他 .NET 新引入的类型上，如 TimeOnly 类型。对于 TimeOnly 类型，可以采用类似的解决方案：

options.MapType<TimeOnly>(() => new OpenApiSchema {
    Type = "string",
    Format = "time"
});

最佳实践

为了确保 API 文档的准确性，建议开发者在以下场景中特别注意：

1. 当使用较新版本的 .NET 引入的新类型时
2. 当升级 Swashbuckle.AspNetCore 版本后
3. 当 API 文档显示与预期不符时

定期检查 API 文档的渲染效果，特别是在类型系统发生变化时，可以帮助开发者及时发现并解决类似问题。

随着 Swashbuckle.AspNetCore 的持续更新，这类类型映射问题有望得到更全面的解决，为开发者提供更加无缝的 API 文档生成体验。