Scribe 路由扫描失效主因是未配置 API 前缀扫描或控制器缺 PHPDoc 注释；需在 config/scribe.php 明确设置 'routes' 匹配 api 前缀，并为每个 API 方法添加 @bodyParam 等注释，否则参数标 unknown 或接口遗漏。
路由扫描失效是 Scribe 生成文档时最常卡住的环节——不是工具坏了，而是它根本“看不见”你的 API 路由。核心原因就两个：路由没被识别进来，或识别了但没被它主动扫到。
一、API 路由默认不被扫描
Scribe 默认只扫描 web 中间件组 下的路由，而绝大多数 API 路由都定义在 routes/api.php，自带 api 中间件组。如果你没显式告诉它去扫 api 前缀，它就会跳过整个文件。
- 打开
config/scribe.php，检查'routes'配置项 - 必须写成这样（不能省略）：
'routes' => [
['match' => ['prefix' => 'api']]
],- 如果用了多版本 API（如
v1、v2），可扩展为：
'routes' => [
['match' => ['prefix' => 'api/v1']],
['match' => ['prefix' => 'api/v2']]
],二、控制器方法没注释 = 参数全标 unknown
Scribe 不会从 FormRequest 或 $request->validate() 自动推导字段名和类型，它只认控制器方法上方的 PHPDoc 注释。没有 @bodyParam、@queryParam，它就只能把参数标成 unknown，甚至漏掉整个接口。
- 每个 API 方法顶部必须加注释块，哪怕只是占位
- 示例（POST 创建用户）：
/** * @bodyParam name string required 示例: 张三 * @bodyParam email string required 示例: zhang@example.com * @bodyParam avatar file optional */
- 别写
@param或@return—— Scribe 完全忽略这些 - 用
@response提供真实 JSON 结构，比空写更有价值
三、“No routes found” 的真实原因
报这个错，90% 是以下两种情况之一：
-
路由没加
api/前缀：比如你写了Route::get('users', ...)，但没放在Route::prefix('api')组里，Scribe 就找不到 -
用了
Route::apiResource()却没补注释：Scribe 不解析隐式行为，必须在路由定义前手动加/** @group Users */这类分组注释
验证方法：运行 php artisan route:list --compact，确认目标路由确实存在且 Method/URI/Action 三列齐全。如果列表里压根没有，问题不在 Scribe，而在 Laravel 路由加载本身。
四、生成后点「Try it out」失败？那是中间件在拦路
Scribe 文档页里的测试功能是在浏览器里发真实请求，但它不会自动携带 Sanctum token 或绕过 throttle 限流。所以即使文档生成成功，点击测试也大概率返回 401 或 429。
- 开发阶段建议临时禁用相关中间件（如注释掉
auth:sanctum或throttle:60,1） - 或者在
config/scribe.php的'auth'配置中明确指定中间件名（注意不是auth:sanctum，而是'sanctum'） - 更稳妥的做法：把文档当静态说明看，接口测试仍走 Postman 或 PHPUnit
