PHP 属性在 Laravel 10+ 中无法被 Scribe 或 l5-swagger 等主流文档工具直接解析生成 API 文档，仍需依赖传统 PHPDoc 注释（如 @bodyParam、@OA\Get）；仅 FormRequest 中的 rules() 可被 Scribe 自动提取，属性本身不参与文档生成。
在 Laravel 10+（尤其搭配 PHP 8.1+）项目中，PHP 属性（Attributes）正逐步替代传统 PHPDoc 注释用于描述接口行为，但目前主流文档生成工具尚未原生支持属性语法直接生成 API 文档。这不是 Laravel 的“新特性”，而是生态适配的现实断层——你写对了属性，工具却读不到。
为什么 @OA\Get 或 @bodyParam 注释仍不可弃
Scribe（当前最推荐的 Laravel 文档工具）和 darkaonline/l5-swagger 都不解析 PHP 属性，它们依赖传统 DocBlock 中的特定标签：
-
@bodyParam name string required→ 被 Scribe 自动提取为请求体字段 -
@OA\Get(path="/users")→ 被 l5-swagger 解析为 OpenAPI 操作对象 -
#[Validate(['name' => 'required|string'])]→ Scribe 能识别 FormRequest 类里的rules()，但不会读取这个属性本身
也就是说：即使你在控制器方法上写了 #[MapResource(UserResource::class)] 或 #[Middleware('auth:sanctum')]，这些信息不会自动出现在生成的文档里，除非你用对应注释显式声明（如 @authenticated、@response）。
哪些属性能被间接利用？
部分属性虽不直出文档，但可被工具链“感知”：
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
立即学习“PHP免费学习笔记（深入）”；
-
#[Validate]和#[ValidateIf]：Scribe 不读它们，但如果你把验证逻辑封装进FormRequest类，并在控制器中使用该类（store(StoreUserRequest $request)），Scribe 就能自动读取其rules()方法并生成参数说明 -
#[ScopeBindings]或#[WithoutModelEvents]：纯运行时行为，与文档无关，无需注释补充 -
#[OnQueue]等队列属性：API 文档不体现异步执行细节，通常也不需文档化
中文场景下的实操建议
别为了“用新语法”而牺牲文档可用性。真实团队协作中更稳妥的做法是：
- 继续用
/** @bodyParam ... */写参数说明，确保 Scribe 能提取；属性只用于运行时逻辑控制 - 若已大量使用 PHP 属性做验证，可保留
FormRequest类，它天然兼容 Scribe，无需额外注释 - 避免混用：不要在一个方法上既写
#[Validate]又写@bodyParam，容易造成语义重复或冲突 - 中文文档显示正常，只需在
config/scribe.php中确认'language' => 'zh'并启用中文字体支持（如 Noto Sans SC）
工具没跟上语言演进很正常。现阶段，注释不是过时，而是文档生成的事实标准；属性是运行时增强，二者分工明确，不必强行统一。
