SpringDoc OpenAPI 3.1 版本中数组类型Schema的显示问题解析

在SpringBoot项目中使用SpringDoc OpenAPI生成API文档时，开发者可能会遇到一个关于数组类型Schema显示的特殊情况。本文将深入分析该问题的技术背景、产生原因以及解决方案。

问题现象

当使用SpringDoc OpenAPI 2.8.0及以上版本时，如果API响应或请求体包含数组类型的对象，在Swagger UI的Schema标签页中会显示为"array "作为根节点，并以"Items"作为数组元素的标识，而不是直接显示数组元素的实际Schema结构。

技术背景

这个问题源于SpringDoc OpenAPI 2.8.0版本的一个重要变更：将默认的OpenAPI规范版本从3.0升级到了3.1。OpenAPI 3.1规范对数组类型的表示方式进行了调整，这种变化直接影响了Swagger UI的渲染方式。

根本原因

OpenAPI 3.1规范对数组类型的Schema定义采用了更加严格的JSON Schema标准。在规范层面，数组类型必须明确包含：

1. 类型声明(type: array)
2. 元素定义(items属性)

Swagger UI作为规范的可视化工具，严格遵循了这一标准，因此会显示"array "和"Items"这样的结构标识。

解决方案比较

对于需要保持原有显示方式的开发者，有以下几种选择：

1. 回退到OpenAPI 3.0规范： 在应用配置中添加：

   springdoc.api-docs.version=openapi_3_0
   

   这种方式简单直接，但会失去OpenAPI 3.1的新特性。

2. 适应OpenAPI 3.1的显示方式： 虽然视觉上有所不同，但技术上完全正确，且符合最新规范标准。

3. 自定义Swagger UI： 通过扩展或修改Swagger UI的渲染逻辑，可以实现更符合项目需求的显示方式。

技术建议

对于长期维护的项目，建议：

• 评估是否真的需要修改显示方式，或者可以接受新规范的表示方法
• 如果必须修改，优先考虑配置方式而非代码侵入式修改
• 关注Swagger UI的后续更新，可能会提供更灵活的显示配置选项

总结

这个问题本质上是规范演进带来的显示差异，而非功能缺陷。开发团队需要根据项目实际情况，在规范合规性和UI友好性之间做出权衡。理解OpenAPI规范的演进方向，有助于做出更合理的技术决策。