springdoc-openapi中OpenAPI 3.1规范默认值类型问题解析

在最新版本的springdoc-openapi（2.8.6及以上）中，开发者在使用OpenAPI 3.1规范时可能会遇到一个关于默认值类型的潜在问题。这个问题主要出现在API文档生成过程中，当为模型属性指定默认值时，生成的OpenAPI规范中默认值的类型可能与属性定义的类型不一致。

问题现象

当开发者使用@Schema注解为模型属性指定默认值时，例如：

@Schema(defaultValue = "true")
val completed: Boolean

在OpenAPI 3.0规范下，生成的文档会正确地将默认值表示为布尔类型：

"default": true

但在OpenAPI 3.1规范下，同样的代码生成的文档可能会将默认值表示为字符串类型：

"default": "true"

类似地，对于集合类型的默认值也会出现类型不匹配的情况。例如：

@Schema(defaultValue = "[]")
val items: Set<String>

在3.0规范下会正确生成数组类型的默认值，而在3.1规范下则可能生成字符串类型的默认值表示。

技术背景

OpenAPI规范从3.0版本升级到3.1版本后，虽然规范本身不再强制要求默认值的类型必须与属性类型严格匹配，但仍然强烈建议保持类型一致性。这是为了确保API文档的准确性和工具链的兼容性。

JSON Schema规范（OpenAPI 3.1基于此）明确指出：

建议默认值应与其关联的模式有效匹配

解决方案

对于遇到此问题的开发者，可以采取以下几种解决方案：

1. 升级springdoc-openapi版本：从2.8.7版本开始，对于布尔类型的默认值已经修复了此问题。

2. 临时降级规范版本：如果暂时无法升级，可以将配置改为使用OpenAPI 3.0规范：

springdoc.api-docs.version=openapi_3_0

3. 等待上游修复：对于集合类型等更复杂的情况，需要等待swagger-core项目的相关修复。

最佳实践

为避免此类问题，建议开发者：

• 始终使用与属性类型匹配的默认值表示
• 定期更新springdoc-openapi到最新版本
• 在重要项目中验证生成的OpenAPI文档的有效性
• 对于复杂类型，考虑手动定义Schema而不是依赖自动生成

这个问题提醒我们在使用API文档生成工具时，需要关注规范版本间的差异以及工具链的兼容性问题，确保生成的文档既符合规范要求，又能被下游工具正确解析。