ASP.NET Core OpenAPI 与 Newtonsoft.Json 的兼容性问题解析

背景介绍

在 ASP.NET Core 开发中，OpenAPI 规范的生成是一个重要环节。微软官方提供的 Microsoft.AspNetCore.OpenApi 包是基于 System.Text.Json 构建的，这导致在使用 Newtonsoft.Json 时会出现模型架构不匹配的问题。

核心问题分析

当开发者同时使用 OpenAPI 和 Newtonsoft.Json 时，系统仍然会基于 System.Text.Json 生成 OpenAPI 文档。这会导致请求/响应模型的 JSON 架构与实际序列化行为不一致。

例如，在以下代码中：

public class Foo
{
    [System.Text.Json.Serialization.JsonPropertyName("StjName")]
    [Newtonsoft.Json.JsonProperty("NewtonName")]
    public required string Name { get; set; }
}

OpenAPI 文档会显示属性名为 "StjName" 而非 "NewtonName"，这与实际使用 Newtonsoft.Json 序列化时的行为不符。

技术实现细节

Microsoft.AspNetCore.OpenApi 的设计基于以下技术决策：

1. 完全构建在 System.Text.Json 之上
2. 支持原生 AOT 编译
3. 依赖 Microsoft.OpenApi 库，而该库在 .NET 10 版本中也迁移到了 System.Text.Json

这些设计选择使得支持 Newtonsoft.Json 变得困难，因为需要维护两套完全不同的实现方案。

解决方案建议

对于需要继续使用 Newtonsoft.Json 的开发者，有以下几种选择：

1. 迁移到 System.Text.Json：这是微软推荐的长期解决方案，性能更好且支持异步操作。

2. 双注解模型：为所有模型同时添加 System.Text.Json 和 Newtonsoft.Json 的注解，确保两者行为一致。

3. 使用第三方库：继续使用 NSwag 或 Swashbuckle 等第三方库，它们提供了更灵活的序列化方案选择。

当前限制与未来展望

Microsoft.AspNetCore.OpenApi 目前存在一些限制：

1. 不支持从 XML 文档读取注释（将在 .NET 10 预览版2中支持）
2. 不支持自定义日期时间格式
3. 命名策略不能在类/结构体级别应用

对于这些限制，开发者可以向 dotnet/runtime 仓库提交功能请求，争取在 .NET 10 中获得支持。

总结

虽然 Microsoft.AspNetCore.OpenApi 提供了官方集成的 OpenAPI 支持，但其对 System.Text.Json 的强依赖使得 Newtonsoft.Json 用户需要做出权衡。开发者应根据项目需求，选择最适合的解决方案，平衡兼容性、性能和开发便利性。