Swagger Core中@DefaultValue注解类型转换问题解析

问题背景

在Swagger Core 2.2.22升级到2.2.25版本后，开发者发现了一个关于@DefaultValue注解的类型转换问题。当使用OpenAPI 3.1规范时，无论参数的实际类型是什么（如Boolean、Integer等），@DefaultValue的值都会被强制转换为字符串类型，导致生成的API文档中默认值被错误地加上了引号。

问题表现

以一个简单的REST端点为例：

@GET
@Path("/test")
public void getTest(@DefaultValue(value = "true") @QueryParam(value = "myBool") Boolean myBool) {}

在Swagger Core 2.2.22版本中，生成的OpenAPI文档会正确地表示为：

parameters:
- name: myBool
  in: query
  schema:
    type: boolean
    default: true

但在2.2.25版本中，生成的文档会将默认值错误地表示为字符串：

parameters:
- name: myBool
  in: query
  schema:
    type: boolean
    default: "true"

技术分析

这个问题的根源在于Swagger Core对OpenAPI 3.1规范的支持方式发生了变化。在早期版本中，参数模式是使用特定类型的模式对象（如IntegerSchema、StringSchema等）来表示的，这些类型化的模式对象会调用相应的cast()方法将默认值转换为正确的类型。

然而，在支持OpenAPI 3.1的版本中，所有模式都被表示为JsonSchema类型。这种统一表示虽然简化了代码结构，但也导致了类型转换逻辑的丢失。由于JsonSchema没有针对不同类型实现特定的转换逻辑，默认值就被简单地保留为原始字符串形式。

影响范围

这个问题不仅影响Boolean类型参数，还会影响所有非字符串类型的参数，包括：

• 数值类型（Integer、Long、Float、Double等）
• 布尔类型（Boolean）
• 日期时间类型

解决方案

Swagger Core团队已经在新版本中修复了这个问题。修复方案主要涉及在生成OpenAPI文档时，根据参数的实际类型对默认值进行适当的类型转换。

对于开发者来说，解决方案包括：

1. 升级到包含修复的最新版本
2. 如果暂时无法升级，可以考虑手动调整生成的OpenAPI文档
3. 对于关键API，可以编写测试验证生成的文档是否符合预期

最佳实践

为了避免类似问题，建议开发者在项目中：

1. 为关键API编写契约测试，验证生成的OpenAPI文档是否符合预期
2. 在升级Swagger Core版本时，全面检查生成的API文档
3. 对于复杂的参数类型，考虑使用@Schema注解明确指定类型信息

总结

类型系统的一致性在API文档生成中至关重要。Swagger Core团队通过不断改进对OpenAPI规范的支持，确保了API文档的准确性和可用性。开发者应当关注这类框架级别的变更，以确保API文档能够准确地反映实际的接口行为。