NSwag中JsonIgnoreAttribute被忽略的问题分析与解决方案

问题背景

在NSwag 14.0.4版本中，用户发现一个重要的行为变更：原本在14.0.3版本中能够正常工作的[JsonIgnore]属性突然失效了。这个属性用于标记某些属性不应出现在生成的OpenAPI文档中，但在版本升级后，这些被标记忽略的属性却意外地出现在了API文档里。

根本原因

经过分析，这个问题源于NSwag 14.0.4版本内部的一个重大变更：JSON序列化器从Newtonsoft.Json切换到了System.Text.Json。这个变更导致了以下具体问题：

1. 当使用[Newtonsoft.Json.JsonIgnore]属性时，新版本的System.Text.Json序列化器无法识别这个来自不同库的忽略标记
2. 虽然两个库都有JsonIgnore属性，但它们属于不同的命名空间，导致兼容性问题

解决方案

针对这个问题，开发者可以采用以下几种解决方案：

方案一：改用System.Text.Json的忽略属性

最简单的解决方案是将属性标记从：

[Newtonsoft.Json.JsonIgnore]
public object? Value

改为：

[System.Text.Json.Serialization.JsonIgnore]
public object? Value

方案二：配置NSwag使用Newtonsoft.Json

如果你需要继续使用Newtonsoft.Json，可以在NSwag配置中明确指定使用Newtonsoft.Json作为序列化器：

{
  "serializer": "NewtonsoftJson"
}

方案三：使用兼容性属性

对于需要同时支持两种序列化器的场景，可以同时使用两种忽略属性：

[Newtonsoft.Json.JsonIgnore]
[System.Text.Json.Serialization.JsonIgnore]
public object? Value

版本兼容性建议

1. 从NSwag 14.0.4开始，默认使用System.Text.Json作为序列化器
2. 如果项目从旧版本升级，需要检查所有[JsonIgnore]属性的来源命名空间
3. 对于新项目，建议直接使用System.Text.Json的忽略属性

总结

NSwag 14.0.4版本的这一变更反映了.NET生态向System.Text.Json迁移的大趋势。开发者需要注意这种底层库变更可能带来的兼容性问题，特别是在属性标记这类细节上。通过理解问题的本质并采用适当的解决方案，可以确保API文档生成的正确性，同时利用新版本带来的性能优势。