Laravel文档完善隐藏功能：生成支持Try-it-out功能的交互式API调试界面【技巧】-php教程-PHP中文网

laravel 中 scribe 的 try-it-out 功能通过内置 /_scribe/tap 端点真实执行控制器逻辑，复用路由、中间件与验证，需配置 'try_it_out' => true、正确 auth 设置、api 前缀匹配及 app_url，并启用中文需设 'default_language' => 'zh'。

laravel文档完善隐藏功能：生成支持try-it-out功能的交互式api调试界面【技巧】

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 原生支持多语言，但需手动启用：

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

在 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 页面按钮、表单、错误提示都会自动显示中文。