NSwag 14.0.4版本中AllowReferencesWithProperties的替代方案

在NSwag 14.0.4版本中，配置JSON Schema生成方式发生了一些变化。对于从旧版本升级的用户来说，一个常见的问题是关于AllowReferencesWithProperties属性的变更。

配置变更背景

在NSwag 13.20.0及更早版本中，开发者可以直接使用AllowReferencesWithProperties属性来配置JSON Schema的生成行为。这个属性主要用于控制当类型被引用时，是否保留其属性定义。

新版本中的正确配置方式

升级到NSwag 14.0.4后，该属性的配置路径发生了变化。现在需要通过Schema配置对象来访问这个设置：

configure.Schema.AllowReferencesWithProperties = true;

实际应用示例

在实际项目中，你可能会在Swagger文档生成配置中这样使用：

services.AddSwaggerDocument(configure => {
    configure.Schema.AllowReferencesWithProperties = true;
    // 其他配置...
});

为什么这个变更重要

这个配置项对于生成准确的API文档非常重要。当设置为true时，即使类型被引用，也会保留其完整的属性定义。这在某些场景下可以避免文档使用者需要跳转查看类型定义，提高文档的可读性。

升级建议

对于从旧版本升级的项目，建议检查所有使用AllowReferencesWithProperties的地方，按照新的配置路径进行更新。同时，可以利用这个机会重新评估是否需要保留这个设置，或者根据项目需求调整其值。

通过理解这个变更，开发者可以更顺利地完成NSwag版本的升级，并确保API文档生成功能正常工作。