Laravel 中 Scribe 的 Try-it-out 功能通过内置 /_scribe/tap 端点真实执行控制器逻辑，复用路由、中间件与验证，需配置 'try_it_out' => true、正确 auth 设置、API 前缀匹配及 APP_URL，并启用中文需设 'default_language' => 'zh'。
Laravel 项目中生成带 Try-it-out 功能 的交互式 API 调试界面，核心不是靠“隐藏功能”，而是正确配置 Scribe 并激活其内置的运行时请求能力。它不依赖外部工具或手动拼接，而是基于 Laravel 自身的路由解析、中间件执行和响应捕获机制实现。
Try-it-out 功能实际怎么工作的
Scribe 的 “Try It Out” 不是模拟请求，而是真实调用你的控制器逻辑：
- 在文档页面点击发送时，前端通过 AJAX 将参数提交到
/_scribe/tap（一个内置调试端点） - 该端点复用 Laravel 的应用上下文，按原路由规则匹配控制器、运行中间件（如
auth:sanctum）、执行验证、调用方法，并截取真实返回体和状态码 - 所以看到的响应结构、字段内容、甚至 422 错误详情，都是你代码跑出来的结果
这意味着：
- 前端不用再猜“这个接口返回空数组还是 null”
- 测试人员可以直接在浏览器里验证 token 过期、权限拦截、分页逻辑是否生效
- 接口改了，只要重新运行
php artisan scribe:generate，文档页里的 Try-it-out 就自动同步
让 Try-it-out 正常工作的关键配置
默认安装后它可能不工作，常见卡点就这几个：
- 确保
config/scribe.php中'try_it_out' => true已开启（新版默认开启） -
'auth' => ['sanctum']或['passport']必须与你项目注册的中间件名完全一致，比如用了middleware('auth:sanctum')，这里就得写'sanctum'，不能写'auth:sanctum' - 若 API 路由加了前缀（如
Route::prefix('v1')->group(...)），需在'routes' => [...]配置里显式包含'prefixes' => ['api/v1/*']，否则 Scribe 扫不到，Try-it-out 就找不到目标路由 -
APP_URL必须配置正确（如https://api.example.com），否则前端构造请求时会发到http://localhost导致跨域或 404
支持认证的实操要点
单纯写 @authenticated 注释不够，必须配合两处设置：
- 控制器方法上加
@authenticated，并确保该路由确实绑定了对应中间件 - 在
config/scribe.php的'auth'数组中声明认证方式，同时'use_implicit_auth_headers' => true（默认为 true），这样 Try-it-out 才会自动注入Authorization: Bearer {token}头 - Token 可手动填入输入框，也可提前在文档页右上角登录入口完成 Sanctum 登录，后续所有请求自动复用
中文界面与友好提示
Scribe 原生支持多语言，但需手动启用：
- 在
config/scribe.php中设'default_language' => 'zh' - 所有注释标签（如
@queryParam,@bodyParam,@response）里的说明文字直接写中文，例如：/** * 创建订单 * @bodyParam goods_id integer required 商品 ID * @bodyParam quantity integer required 购买数量，默认为 1 * @response 201 {"order_no":"ORD20260605001","status":"pending"} */
不需要额外翻译文件，生成的 HTML 页面按钮、表单、错误提示都会自动显示中文。
预览时别跳过本地服务启动
直接双击 public/docs/index.html 会白屏——因为 JS 加载 /openapi.json 和 /_scribe/tap 时触发跨域限制。
正确做法是：
- 开发阶段用 PHP 内置服务器：
php -S localhost:8000 -t public/docs - 然后访问
http://localhost:8000，就能完整使用 Try-it-out、登录、参数填写、实时响应查看
部署到 Nginx 或 Apache 时，要确保 /docs/ 下的静态资源可被直接读取，且 /_scribe/tap 路由能被 Laravel 应用接管（即不能被重写规则屏蔽）。
不复杂但容易忽略
