Swagger Core中集合类型参数@Pattern注解失效问题解析

问题背景

在使用Swagger Core生成OpenAPI 3.1.0规范时，开发人员发现当在集合类型（如List）的类型参数上使用@Pattern注解时，生成的OpenAPI文档中不会包含预期的正则表达式模式约束。这个问题主要影响那些需要在集合元素上定义字符串模式验证的场景。

问题现象

考虑以下Java类定义：

public class DtoUsingPatternOnCollection {
    private List<@Pattern(regexp = "myPattern") String> myField;
    
    // getter和setter方法
}

按照预期，生成的OpenAPI文档应该在myField数组的items部分包含pattern: myPattern的定义。但在OpenAPI 3.1.0规范下，这个模式约束没有被正确生成。

技术原理分析

这个问题源于Swagger Core内部对Bean Validation注解的处理逻辑。在ModelResolver.applyBeanValidatorAnnotations方法中，处理@Pattern注解时存在类型检查逻辑：

1. 该方法会检查属性是否是StringSchema类型
2. 或者检查属性的items是否是StringSchema类型

在OpenAPI 3.0.x版本中，这种检查能够正常工作，因为集合元素的schema类型确实是StringSchema。但在OpenAPI 3.1.0中，schema类型系统发生了变化，集合元素的schema类型变为JsonSchema，导致原有的类型检查失效。

解决方案

修复方案的核心思想是将硬编码的类型检查改为基于schema类型的检查。具体来说：

1. 不再使用instanceof StringSchema这样的硬编码检查
2. 改为检查schema的type或types字段，判断是否为字符串类型
3. 这样无论底层实现是StringSchema还是JsonSchema，只要类型标记为字符串，就能正确处理@Pattern注解

影响范围

这个修复主要影响以下使用场景：

1. 使用OpenAPI 3.1.0规范的项目
2. 在集合类型（List、Set等）的类型参数上使用@Pattern注解
3. 需要为集合元素定义字符串模式约束的情况

最佳实践

为避免类似问题，建议开发人员：

1. 明确指定使用的OpenAPI规范版本
2. 对于复杂的验证场景，考虑使用@Schema注解进行补充说明
3. 在升级Swagger Core版本时，注意检查生成的OpenAPI文档是否符合预期

总结

这个问题展示了在不同OpenAPI规范版本间类型系统变化带来的兼容性挑战。通过将硬编码的类型检查改为基于类型标记的检查，Swagger Core能够更好地适应不同版本的规范要求，确保注解信息能够正确转换为OpenAPI文档。这个修复已经包含在Swagger Core的最新版本中，受影响的用户可以升级版本来解决这个问题。