嵌套数组参数文档需明确三点：字段名用 addresses0 格式而非点号；验证规则写为 addresses.*.city 并声明 addresses=>array；提供含边界情况的真实 json 示例。
为嵌套数组参数写清楚文档注释，核心是三点：字段命名要和前端提交一致、验证规则路径要可读、示例数据要贴实际场景。光靠代码注释本身不能自动映射结构，得配合工具（比如 laravel-apidoc-generator）才能生成可交互的文档。
字段名必须用方括号语法，文档里要明确写出
浏览器表单或 FormData 提交嵌套数据时，name 属性必须写成 addresses[0][city] 这种格式，而不是 addresses.0.city 或 addresses_city。文档注释里要直接展示这个真实字段名，避免让前端猜路径。
- ✅ 正确示例：
@bodyParam addresses[0][city] string 城市名称，必填 - ❌ 错误写法：
@bodyParam addresses.0.city string（这不是实际提交的键名） - 动态新增项也要体现索引逻辑，比如 JS 添加第 3 条地址时，name 应为
addresses[2][zip]
验证规则路径用点号，但文档需说明对应关系
Laravel 验证器内部把 addresses[0][city] 自动转成 addresses.0.city 路径来匹配规则，所以文档中既要写原始字段名，也要注明验证规则写法。
- 在注释里加一句说明：“该字段验证规则为
addresses.*.city => required|string，且顶层需声明addresses => array” - 避免只写规则不提约束条件，比如漏掉
addresses => array会导致整个嵌套验证失效 - 深层嵌套如
orders[0][items][1][price]，对应规则是orders.*.items.*.price，文档中可分层列出结构示意
提供真实、可运行的 JSON 示例
纯文字描述嵌套结构容易歧义，直接给一段带缩进的 JSON 示例最直观。注意 Content-Type 必须是 application/json，否则 Laravel 不会自动解析多维数组。
- 示例应包含典型边界情况：空数组、单条、多条、含可选字段
- 比如提交多个联系人：
{<br> "contacts": [<br> {"name": "张三", "phone": "13800138000"},<br> {"name": "李四", "phone": "13900139000", "email": "lisi@example.com"}<br> ]<br>} - 在注释中标注关键点：“contacts 是数组，每项为对象；email 字段可选，但 name 和 phone 必填”
API 文档生成器要开启嵌套支持
用 laravel-apidoc-generator 时，默认能识别方括号字段名，但复杂结构需要额外配置：
- 确保路由方法上有完整注释，包括
@bodyParam和@response - 在
config/apidoc.php中启用'strategies' => ['metadata' => [...]]，加入处理嵌套的策略类 - 对
files.*.size这类通配规则，文档会自动展开为“files[0].size、files[1].size……”，无需手动列每一条
