NSwag中JsonIgnoreAttribute失效问题解析

问题背景

在NSwag 14.0.4版本中，用户报告了一个关于JsonIgnore属性失效的问题。具体表现为：在14.0.3版本中，使用Newtonsoft.Json.JsonIgnore标记的属性会被正确忽略，不会出现在生成的OpenAPI文档中；但在升级到14.0.4版本后，这些被标记忽略的属性却出现在了文档中。

问题原因分析

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

1. 原有的Newtonsoft.Json.JsonIgnore属性不再被新的序列化器识别
2. 新的序列化器System.Text.Json有自己的忽略属性System.Text.Json.Serialization.JsonIgnore
3. 版本升级后，如果没有相应调整代码，会导致原本应该被忽略的属性暴露在API文档中

解决方案

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

方案一：改用System.Text.Json的JsonIgnore

public class MyClass
{
    [System.Text.Json.Serialization.JsonIgnore]
    public object? Value { get; set; }
    
    // 其他属性...
}

这是最直接的解决方案，完全适配新的序列化器。

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

如果项目中有大量现有代码使用Newtonsoft.Json的特性，可以考虑配置NSwag继续使用Newtonsoft.Json作为序列化器。这需要在NSwag配置中进行相应设置。

方案三：同时支持两种序列化器

对于需要同时支持新旧版本的项目，可以使用条件编译：

public class MyClass
{
#if NETCOREAPP3_0_OR_GREATER
    [System.Text.Json.Serialization.JsonIgnore]
#else
    [Newtonsoft.Json.JsonIgnore]
#endif
    public object? Value { get; set; }
}

版本兼容性建议

1. 在升级NSwag版本时，特别是跨大版本升级时，应该仔细阅读变更日志
2. 对于生产项目，建议先在测试环境验证新版本的兼容性
3. 对于大型项目，可以考虑分阶段迁移，先更新序列化相关代码，再升级NSwag版本

总结

NSwag 14.0.4版本的这一变更反映了.NET生态向System.Text.Json迁移的趋势。开发者需要了解这一变化，并及时调整代码以适应新的序列化器。虽然这种变更短期内可能带来一些迁移成本，但从长远来看，使用System.Text.Json能带来更好的性能和更现代的API设计。