NSwag 在生成 OpenAPI 文档时处理重复 JSON 属性的解决方案

问题背景

在使用 NSwag v14 版本生成 OpenAPI 文档时，开发者可能会遇到一个特定的错误："The JSON property 'item' is defined multiple times on type 'Google.Protobuf.Reflection.MessageDescriptor+FieldCollection'"。这个错误通常发生在升级到 NSwag v14 和 .NET 8.0 后，特别是当项目中使用了 Google.Protobuf 相关库时。

错误分析

这个错误的核心问题是 JSON 序列化过程中发现了重复的属性定义。具体来说：

1. 重复属性问题：系统检测到 'item' 属性在 Google.Protobuf.Reflection.MessageDescriptor.FieldCollection 类型中被多次定义
2. 版本升级影响：从 NSwag v13 升级到 v14 后，JSON 序列化处理逻辑变得更加严格
3. 依赖关系：问题通常与 Google.Protobuf 库或依赖它的库（如 Google.OrTools）有关

根本原因

经过深入分析，这个问题通常是由于以下原因之一：

1. 不恰当的序列化对象：某些对象包含不应该被序列化为 JSON 的字段或属性
2. 反射机制变化：NSwag v14 对反射处理逻辑进行了改进，能更准确地检测属性定义
3. 上下文对象泄漏：开发者的业务对象可能包含了仅供内部使用的上下文对象

解决方案

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

1. 使用 JsonSchemaIgnore 特性

[JsonSchemaIgnore]
public SomeType ContextField { get; set; }

这个特性会告诉 NSwag 在生成 OpenAPI 文档时忽略指定的属性。

2. 自定义序列化设置

对于更复杂的情况，可以自定义 JSON 序列化设置：

services.AddOpenApiDocument(document =>
{
    document.SerializerSettings = new JsonSerializerSettings
    {
        ContractResolver = new CustomContractResolver()
    };
});

3. 类型排除策略

在 NSwag 配置中明确排除某些类型：

{
  "excludedTypeNames": ["Google.Protobuf.Reflection.MessageDescriptor.FieldCollection"]
}

最佳实践建议

1. 明确序列化边界：在设计 API 时，明确哪些对象和属性应该参与序列化
2. 使用 DTO 模式：避免直接序列化领域模型，使用专门的数据传输对象
3. 版本升级测试：在升级 NSwag 或相关依赖时，进行充分的测试
4. 关注日志信息：NSwag 的错误日志通常包含详细的堆栈信息，有助于定位问题

总结

NSwag 是一个强大的 OpenAPI/Swagger 生成工具，但在处理复杂对象图时可能会遇到序列化问题。通过合理使用特性标记和配置，开发者可以有效地控制序列化过程，避免类似重复属性定义的问题。理解这些问题的本质有助于构建更健壮的 API 文档生成流程。