laravel apiresource 不能自动生成 openapi 文档，因其实为运行时数据转换工具而非契约描述；必须在控制器方法中用 @response、@responsecollection、@responsefield 等注解显式声明响应结构，而非依赖 resource 类自动推导。
laravel-api-resources 怎么自动生成 OpenAPI 文档
不能直接生成。Laravel 的 ApiResource 类本身不包含 OpenAPI 元数据，也不会被 scribe 或 laravel-openapi 自动识别为接口定义来源。
常见错误是以为只要写了 App\Http\Resources\UserResource，文档工具就能“猜出”响应结构——实际它只负责数据转换，不声明 schema。
- 必须手动补充响应结构描述，比如在控制器方法上加
@response注解或使用->response()链式调用配合注释 - 推荐用
scribe+@group/@bodyParam/@responseField组合，而不是依赖 Resource 类自动推导 -
laravel-openapi要求你显式定义Operation和Response，Resource 类只能作为参考，不能替代 schema 声明
用 scribe 生成 API 文档时，resource 返回值怎么写注释
关键不是 Resource 类本身怎么写，而是控制器里调用它的那个动作方法怎么注释。
比如你返回 UserResource::collection($users)，scribe 不会去解析这个类的 toArray()，它只认你写的 @response 或 @responseCollection。
- 对集合响应，用
@responseCollection App\Http\Resources\UserResource，并确保该类有public $wrap = 'data'这类可预测的包装逻辑 - 如果用了自定义 key（如
return response()->json(['items' => $resource])），就必须用@response手动写 JSON 示例，否则文档里还是空的 -
@responseField可以逐字段说明，比靠 Resource 类推断更可靠，尤其当toArray()里有动态键或条件字段时
为什么 laravel-api-resources 和 openapi spec 对不上
因为两者设计目标不同：Resource 是运行时数据塑形工具，OpenAPI 是契约描述语言。Resource 可以在 toArray() 里做任意 PHP 逻辑，而 OpenAPI 要求静态、可枚举的结构。
典型脱节场景：
- Resource 中用了
when()动态添加字段 → OpenAPI 文档里没体现可选性，需手动加@responseField nullable - Resource 返回了 Eloquent 关系（如
$this->whenLoaded('posts')）→ 文档不会自动展开嵌套结构，得用@responseField posts[].id显式声明 - Resource 构造器接收了非模型参数（如
new UserResource($user, $includeMeta = true)）→ OpenAPI 没法反推这个布尔参数的影响，必须靠注释说明
不改 Resource 类的前提下，让文档准确反映响应结构
最省事的做法是绕过 Resource 类的“黑盒”，直接基于最终输出写文档。
实操建议：
- 用
php artisan scribe:generate --force后，检查生成的resources/docs/index.html里响应体是否和curl -X GET /api/users实际返回一致；不一致就回退到控制器方法补@response - 如果项目已大量使用 Resource，可写个简单脚本提取
toArray()的键名（注意过滤掉$this->merge()和when()分支），生成基础@responseField列表，再人工补全类型和说明 - 避免在 Resource 中做复杂格式转换（如把时间戳转成中文字符串），这类逻辑会让文档和代码越来越难同步
真正麻烦的不是 Resource 怎么写，而是团队是否接受“文档即契约”——一旦允许 Resource 随意变形，文档就只能靠人肉维护。
