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，即使用此技能。

下载

• #[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）

工具没跟上语言演进很正常。现阶段，注释不是过时，而是文档生成的事实标准；属性是运行时增强，二者分工明确，不必强行统一。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！