SpringDoc OpenAPI 1.6.5下如何使用@ArraySchema注解为嵌套List设置maxItems限制？

我刚好在SpringDoc 1.x版本里处理过类似的嵌套List约束配置问题，你的核心问题是没搞清楚@ArraySchema和@Schema在嵌套场景下的正确组合方式——之前的写法要么类型不兼容，要么没逐层指定数组约束导致语义验证错误。

问题根源 #

对于嵌套的List<List<Obj>>、List<List<List<Obj>>>这类结构，每一层数组都需要明确声明约束（比如maxItems），但@ArraySchema的schema属性要求传入的是@Schema类型，而不是另一个@ArraySchema，这就是你遇到类型不兼容报错的原因。

正确写法示例 #

1. 双层嵌套List（List<List<Obj>>）

@Schema(
    type = "array",
    arraySchema = @ArraySchema(
        maxItems = 5, // 外层List的最大元素数量
        schema = @Schema(
            type = "array",
            arraySchema = @ArraySchema(
                maxItems = 2, // 内层List的最大元素数量
                schema = @Schema(description = "单个Obj对象的描述")
            )
        )
    )
)
private List<List<Obj>> test;

2. 三层嵌套List（List<List<List<Obj>>>）

@Schema(
    type = "array",
    arraySchema = @ArraySchema(
        maxItems = 3, // 最外层List的maxItems
        schema = @Schema(
            type = "array",
            arraySchema = @ArraySchema(
                maxItems = 5, // 中间层List的maxItems
                schema = @Schema(
                    type = "array",
                    arraySchema = @ArraySchema(
                        maxItems = 2, // 最内层List的maxItems
                        schema = @Schema(description = "单个Obj对象的描述")
                    )
                )
            )
        )
    )
)
private List<List<List<Obj>>> listOfTest;

关键逻辑说明 #

• 每一层嵌套的数组都需要用@Schema(type = "array")来声明这是一个数组类型
• 通过@Schema的arraySchema属性，指定当前层数组的约束（比如maxItems），同时通过arraySchema里的schema属性定义下一层元素的结构
• 如果下一层元素还是数组，就重复@Schema(type = "array") + @ArraySchema的组合；如果是普通对象，直接用@Schema描述即可

这种写法完美适配SpringDoc OpenAPI 1.6.5版本的规则，既能满足每层数组的maxItems约束配置，也不会出现类型不兼容或语义验证错误。

内容的提问来源于stack exchange，提问作者KeshavBoh