如何在Spring自动RestDocs中为集合内部元素约束生成文档

核心结论 #

Spring RestDocs 无内置能力直接支持集合类型字段的泛型元素级约束文档生成，你遇到的约束错分类问题属于框架原生实现的设计局限，并非你修改解析逻辑的操作有误。

原生实现的具体问题 #

• 你定位到的 ValidatorConstraintResolver 核心解析逻辑（对应仓库代码第64行），仅针对字段本身直接关联的注解做约束提取，完全没有补充泛型参数类型上的约束解析分支，原生状态下根本无法获取到 List<@NotBlank String> 这类写法里标在泛型参数上的约束信息。
• 你自行修改解析逻辑拿到元素级约束后出现的分类错误，本质是元数据绑定逻辑的错位：框架会把所有解析到的约束，默认绑定到集合根字段的元数据对象上。因为集合字段本身没有标注非空约束，分类器就会将整个条目判定为Optional类型，连带把本该属于集合元素的@NotBlank约束也错误归到该分类下。

可落地的解决方式 #

• 不要直接修改框架源码，基于框架提供的 ConstraintResolver 扩展接口自定义实现解析逻辑即可：
  • 识别字段类型为参数化集合类型时，单独提取泛型实际类型参数上标注的所有约束注解
  • 为集合元素对应的文档路径（通常格式为someAnotherUsefulInformationList[]）单独绑定对应的约束元数据，和集合根字段的元数据做完全隔离
  • 集合根字段的约束单独按字段本身的注解规则判定分类，不要和元素级约束做关联绑定
  • 这种层级化的元数据绑定逻辑，就能彻底避免元素级约束被错误归类的问题。

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