Swagger UI中OpenAPI 3.1.0模型展开深度配置问题解析

在最新版本的Swagger UI 5.11.0中，开发者发现了一个关于OpenAPI 3.1.0规范支持的重要问题。当使用defaultModelExpandDepth配置参数时，该设置无法正确应用于包含oneOf、anyOf和allOf组合关键字的Schema定义部分。

这个问题的具体表现是：在渲染OpenAPI 3.1.0文档时，虽然普通对象类型的属性能够按照配置的展开深度正确显示，但使用了组合关键字的Schema部分却始终保持着默认的折叠状态，无论defaultModelExpandDepth设置为何值。

从技术实现角度来看，这个问题源于Swagger UI的模型渲染逻辑在处理组合关键字时没有正确继承全局的展开深度配置。在OpenAPI 3.1.0规范中，oneOf、anyOf和allOf是用于构建复杂Schema的重要工具，它们允许开发者通过组合多个Schema定义来描述更灵活的数据结构。

对于API文档使用者来说，这个缺陷会导致无法直观地查看完整的API响应结构，特别是当响应模型使用了这些组合关键字时。开发者不得不手动点击展开每个组合部分，这在处理复杂API时尤其不便。

该问题已在最新的代码提交中得到修复。修复方案确保了展开深度配置能够正确传播到所有Schema部分，包括使用了组合关键字的定义。这意味着现在开发者可以像配置普通Schema一样，控制组合Schema的初始展开状态。

这个改进对于提升OpenAPI 3.1.0文档的浏览体验具有重要意义，使得复杂API模型的展示更加一致和可控。对于使用Swagger UI展示API文档的项目来说，建议关注这个修复并考虑升级到包含该修复的版本。