API文档生成依赖控制器注解而非Resource类，需用@response/@responseCollection显式声明结构，并确保toArray()返回静态字段、避免动态键和条件逻辑，否则文档与实际响应不一致。
API 资源类本身不生成接口契约，UserResource 写得再完整，scribe 或 laravel-openapi 也不会自动读取它的 toArray() 去生成 OpenAPI 文档——你必须在控制器方法上手动声明响应结构。
控制器里怎么写 @response 才能匹配 Resource 返回值
文档工具只看控制器方法上的注解，不解析 Resource 类。哪怕你返回的是 UserResource::collection($users)，也得用 @responseCollection 显式告诉工具“这是什么结构”。
- 单个资源：用
@response App\Http\Resources\UserResource，并确保该类的toArray()返回的是扁平数组（如['id' => 1, 'name' => '...']），否则文档里字段会错位 - 集合资源：用
@responseCollection App\Http\Resources\UserResource，别写成@response App\Http\Resources\UserCollection——后者是自定义包装类，工具不认识 - 如果
UserResource里用了whenLoaded('profile')这类条件逻辑，必须配@responseField单独说明哪些字段可能缺失，否则文档默认全字段必填
Resource 的 toArray() 里写动态键，文档就对不上
OpenAPI 要求 schema 是静态可枚举的，但 toArray() 允许你写 PHP 表达式，比如 'status_text' => $this->status === 1 ? 'active' : 'inactive'，甚至更复杂的 array_merge() 或循环拼接。这类写法会让文档工具完全无法推断字段类型和存在性。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 避免在
toArray()里用foreach、array_map动态生成键名；改用固定字段 +when()控制显隐 - 如果真要返回键名不确定的结构（如多语言字段
['title_zh' => '...', 'title_en' => '...']），别指望注解自动生成，直接用@response写 JSON 示例字符串 -
@responseField的type和description必须与实际返回值一致，比如日期字段写string($date-time)，别写string就完事
ResourceCollection 的外层结构怎么让文档识别
分页列表接口常用 UserCollection 包装，但它的 toArray() 返回的是 ['data' => [...], 'meta' => [...]]，而 @responseCollection 默认只认 data 里的内容。外层 meta 和 links 不会自动进文档。
- 要么放弃
UserCollection，改用@response写完整 JSON 示例，把data、meta、links全包进去 - 要么在
UserCollection的toArray()里把meta拆成顶层字段（如'total' => $this->total()），然后用多个@responseField分别标注 - 别依赖
with()方法追加字段——它只影响运行时响应，不改变文档生成逻辑
最常被忽略的一点：Resource 类可以任意做数据塑形，但 OpenAPI 文档必须反映真实、稳定、可预测的响应结构。写 @response 不是补漏，而是契约确认——哪怕你改了 toArray() 里一行代码，文档注解也得同步更新，否则前端按文档写的解析逻辑就会崩。
