Scribe 能直接生成 Laravel API 文档，因为它通过解析 PHPDoc 注释（如@bodyParam、@response）、路由定义和显式验证逻辑（FormRequest 或 $request->validate()）自动构建结构化文档，无需抓包或运行接口，支持离线生成。
为什么 Scribe 能直接生成 Laravel API 文档？
因为 Scribe 不依赖你手写 Markdown，而是通过解析 @bodyParam、@response 等 PHPDoc 注释 + 路由定义 + 实际请求逻辑（比如 FormRequest 验证规则），自动拼出结构化文档。它不抓包、不运行接口，所以能离线生成，也避免了 Postman 导出后手动维护的麻烦。
但前提是：你的控制器方法得有规范注释，验证逻辑得在 FormRequest 或方法内用 $request->validate() 显式声明——否则 Scribe 会漏参数或标成 “unknown”。
安装后跑不起来？检查这三处配置
-
config/scribe.php 里 'type' => 'static' 是默认值，别改成 laravel（那是旧版）；新版本只认 static、openapi、homestead
-
'routes' => [['match' => ['prefix' => 'api']]] 这个必须显式配，否则它默认只扫 web 中间件组，API 路由全被跳过
- 如果你用 Sanctum 或 Passport，确保
'auth' => ['sanctum'] 对应中间件名和实际注册名一致；写成 auth:sanctum 就报错
生成时提示 “No routes found” 或参数全是 ?
config/scribe.php 里 'type' => 'static' 是默认值，别改成 laravel（那是旧版）；新版本只认 static、openapi、homestead
'routes' => [['match' => ['prefix' => 'api']]] 这个必须显式配，否则它默认只扫 web 中间件组，API 路由全被跳过'auth' => ['sanctum'] 对应中间件名和实际注册名一致；写成 auth:sanctum 就报错常见于两类情况：路由没加 api 前缀，或者控制器方法没注释。Scribe 不看 Route::apiResource() 的隐式行为，只认显式定义的 @group 和 @bodyParam。
实操建议：
- 给每个 API 方法加
/** @bodyParam name string required 示例: 张三 */，哪怕只是占位 - 用
php artisan scribe:generate --force强制重写，避免缓存干扰 - 如果用了
apiResource，在routes/api.php里补上注释块：/** * @group Posts */
放在Route::apiResource('posts', ...)上方
生成的 HTML 文档打不开或样式错乱？
Scribe 默认输出到 public/docs，但不会自动加 .htaccess 或配置 Nginx rewrite。直接双击 index.html 会因跨域加载 JS 失败，显示空白页。
解决办法只有两个：
- 用内置服务器预览：
php -S localhost:8000 -t public/docs，然后访问http://localhost:8000 - 把
public/docs当作子目录部署，确保 Web 服务器允许index.html作为入口，并且静态资源路径没被重写规则拦截
另外，别动 resources/views/vendor/scribe 下的模板——升级 Scribe 时会被覆盖，自定义样式应通过 scribe.php 的 'theme' => 'default' 配置项配合外部 CSS 注入，而不是改 vendor 文件。
