ASP.NET Core 10中Swagger对可空属性示例值生成的问题解析

在ASP.NET Core 10的版本更新中，开发团队将OpenAPI规范从3.0.1升级到了3.1.1版本。这一变更虽然带来了许多新特性，但也引入了一些兼容性问题，特别是在Swagger UI生成示例值方面表现尤为明显。

当我们在.NET 10中使用Microsoft.AspNetCore.OpenApi和Swagger时，如果模型类中包含可空属性，Swagger UI生成的示例值会出现异常情况。例如，对于以下模型定义：

public class TodoRequest
{
    [Required]
    public string? Description { get; set; } = null!;
    public DateTimeOffset? DueDate { get; set; }
    [Required]
    public Priority? Priority { get; set; }
    public List<string>? Tags { get; set; } = [];
}

在.NET 9环境下，Swagger UI能够正确生成示例值，显示合理的默认值。但在.NET 10中，生成的示例值会将可空属性显示为null，即使这些属性被标记为[Required]或有默认值。

这一问题的根源在于OpenAPI 3.1.1规范对可空类型的处理方式发生了变化。新规范中，可空属性会被表示为类型数组，其中包含"null"和实际类型。例如，对于可空字符串属性，规范会生成：

"description": {
    "type": [
        "null",
        "string"
    ]
}

而Swagger UI在5.20.4版本之前，对这种新的类型表示方式处理不够完善，导致示例值生成异常。特别是当"null"出现在类型数组的第一个位置时，Swagger UI会优先选择null作为示例值。

这个问题不仅影响Swagger UI，也影响其他OpenAPI文档工具如Scalar和ReDoc。幸运的是，Swagger UI团队在5.20.4版本中修复了这个问题，现在能够正确处理OpenAPI 3.1.1规范中的可空类型表示。

对于开发者而言，如果遇到类似问题，可以考虑以下几种解决方案：

1. 升级Swagger UI到5.20.4或更高版本
2. 暂时回退到OpenAPI 3.0.1规范
3. 手动调整生成的OpenAPI文档，将实际类型放在类型数组的首位

这个问题提醒我们，在升级框架版本时，特别是涉及规范变更时，需要全面测试API文档生成功能，确保向后兼容性。同时，也展示了开源社区快速响应和解决问题的效率，为开发者提供了良好的升级路径。