未知maxItems时，如何合规定义OpenAPI Schema中的数组？

分页返回接口场景 #

支持自定义页大小和页码的分页接口，确实没法固定死maxItems——毕竟单页数据量由请求里的页大小参数说了算，总数据量还可能动态变化。这里给两个实用的处理方式：

• 对接后端实际限制：如果你的后端对页大小有硬上限（比如最多允许每页拉200条），直接把这个上限值设为maxItems。这比设100万这种超大值合理得多，还能准确反映接口的真实行为，完全符合规范要求。
• 常规值+描述补充：要是后端没做硬限制，先选一个符合业务常规的数值（比如100）当maxItems，同时在Schema的description里写清楚：“实际返回条目数由请求的页大小参数决定，最大可返回数量受系统配置约束”，既满足审计的必填要求，也能让使用者明白实际逻辑。

错误数组返回接口场景 #

错误数组的长度完全取决于校验规则或业务异常情况，比如表单提交时的字段错误数。处理思路如下：

• 按业务场景估最大值：根据实际业务逻辑估算，比如表单最多有50个输入字段，就把maxItems设为50；如果是全局系统错误，设个10以内的数就行。这个值不用绝对精准，只要覆盖业务中可能出现的最大错误数量就够。
• 用描述补全信息：在Schema里加一句描述，比如“返回的错误条目数由校验失败或业务异常情况决定，最大值为[X]”，让调用方清楚这个值的实际意义。

关于规范要求的补充 #

OpenAPI规范本身里maxItems是可选字段，但部分审计工具会把它设为强制检查项。如果真的没法确定合理的最大值，也可以在审计备注里说明：该接口返回数组的长度由请求参数或业务场景动态决定，无法固定最大值，已通过Schema的description明确告知使用者。

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