Swagger Core中@Size注解对集合类型请求体参数失效问题解析

问题背景

在Swagger Core 2.2.22升级到2.2.25版本后，开发者发现了一个关于参数验证注解的重要变更：当使用@Size注解标注集合类型的请求体参数时，生成的OpenAPI规范中不再包含预期的minItems和maxItems约束。这个问题主要影响使用OpenAPI 3.1规范的开发者。

问题表现

考虑以下典型的REST端点定义：

@GET
@Path("/test")
public void getTest(@Size(min = 1, max = 100) List<String> myList) {}

在Swagger Core 2.2.22版本中，会正确生成包含集合大小约束的OpenAPI规范：

requestBody:
  content:
    application/json:
      schema:
        maxItems: 100
        minItems: 1
        type: array
        items:
          type: string

但在2.2.25版本中，生成的规范丢失了这些约束信息：

requestBody:
  content:
    application/json:
      schema:
        type: array
        items:
          type: string

技术原因分析

问题的根源在于ParameterProcessor.applyAnnotations方法中对@Size注解的处理逻辑。该方法原本通过检查parameter.getSchema()是否为ArraySchema实例来决定是否应用大小约束。但在新版本中，schema类型变为了JsonSchema，导致约束条件无法正确传播到生成的规范中。

这种变化反映了Swagger Core内部对OpenAPI 3.1规范支持的演进过程。OpenAPI 3.1引入了JSON Schema的支持，导致原有的类型检查机制不再适用。

解决方案

开发团队已经修复了这个问题，解决方案类似于之前处理类似问题的方法：不再依赖instanceof ArraySchema检查，而是改为检查schema的type或types字段，确保属性确实是数组类型。

对于急需解决问题的开发者，可以采用以下临时解决方案：

@GET
@Path("/test")
public void getTest(
    @ArraySchema(minItems=1, maxItems=100)
    @Size(min = 1, max = 100) 
    List<String> myList
) {}

通过显式添加@ArraySchema注解，可以确保生成的OpenAPI规范包含正确的大小约束信息。

最佳实践建议

1. 版本兼容性检查：在升级Swagger Core版本时，应特别关注参数验证相关的变更，进行充分的测试验证。

2. 注解组合使用：对于关键的业务参数，考虑同时使用@Size和@ArraySchema注解，提高代码的健壮性。

3. 规范验证：生成OpenAPI规范后，建议使用规范验证工具确保所有约束条件都被正确转换。

4. 测试覆盖：为包含参数约束的接口添加专门的测试用例，验证生成的规范是否符合预期。

这个问题提醒我们，在API文档生成过程中，注解处理器与规范版本之间的兼容性是需要特别关注的领域。随着OpenAPI规范的演进，相关的工具链也需要不断调整以适应新的规范要求。