Scribe无法正确显示自定义验证规则描述的根本原因是其仅解析Laravel内置规则注释，对闭包、全局扩展规则及Rule类缺乏语义识别能力；推荐方案是确保Rule类实现Rule接口并提供返回字符串的message()方法，且该类需被实际调用、命名空间需在config/scribe.php中正确配置。
Scribe 无法在生成的 API 文档中正确显示自定义验证规则的描述（比如 “手机号格式不正确”），根本原因不是规则本身失效，而是 Scribe 默认只解析 Laravel 内置规则的注释逻辑，对自定义规则（尤其是闭包、全局扩展规则、Rule 类）缺乏语义识别能力——它“看见”了规则名，但不知道该怎么翻译成可读文案。
确保 Rule 类自带清晰的 message() 方法
这是最推荐、最可控的方式。Scribe 能直接读取 Rule 类中的 message() 返回值，并作为参数描述写入文档。
- Rule 类必须实现
IlluminateContractsValidationRule接口，且message()方法返回字符串（不能是数组或 JSON） - 避免在
message()中动态拼接字段名（如return $this->attribute . ' 格式错误';），Scribe 不解析变量，会原样输出或报错 - 示例正确写法：
public function message(): string { return '请输入有效的中国大陆手机号码'; } - 生成文档前，确认该 Rule 类已被实际用于某条路由的验证逻辑（Scribe 只扫描被调用的规则）
为全局 Validator::extend 规则补充语言包条目
如果你用 Validator::extend('phone_zh', ...) 方式注册了规则，Scribe 会尝试从语言文件中查找对应提示——但它不会自动 fallback 到闭包里的错误信息。
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 打开
resources/lang/zh_CN/validation.php（或你当前 locale 对应的语言文件） - 在
'custom' => []数组内添加键值对：'phone_zh' => ':attribute 格式不正确' - 确保 key 名与
extend()第一个参数完全一致（区分大小写、下划线） - 若使用多语言，所有启用的 locale 目录下都要同步添加该条目，否则非中文环境可能显示英文默认提示
避免在 FormRequest 中混用闭包规则 + Scribe 文档生成
闭包规则（function($attr, $val, $fail) { ... }）无法被 Scribe 解析出描述文字，因为它没有类名、没有 message 方法、也不参与语言包映射。
- Scribe 扫描到这类规则时，通常标记为
unknown或留空，文档中仅显示规则名（如closure） - 临时调试可用，但正式 API 文档需替换为 Rule 类或全局扩展规则
- 若必须保留闭包，可在 PHPDoc 的
@bodyParam注释中手动补全说明，例如：@bodyParam phone string required 手机号码，11位中国大陆手机号
检查 config/scribe.php 的 rules 命名空间配置
Scribe 需要知道去哪里找你的 Rule 类，否则即使类存在，也可能跳过解析。
- 打开
config/scribe.php，找到'rules' => [...]配置项 - 确认已包含你的 Rule 类所在命名空间，例如：
'App\Rules\*'或'App\Rules\ValidPhoneNumber' - 如果 Rule 类放在非标准目录（如
app/Validation/Rules/），需显式添加该路径模式 - 修改后运行
php artisan config:clear再执行php artisan scribe:generate
