用Scribe为Laravel生成可交互API文档只需三步：装对（composer require --dev knuckleswtf/scribe + php artisan scribe:install）、注清（在控制器中用@group、@queryParam、@bodyParam等标签规范注释）、跑通（php artisan scribe:generate后php -S localhost:8000 -t public/docs预览）。
用 Scribe 为 Laravel 项目生成第一份可交互 API 文档，核心就三件事：装对、注清、跑通。不需要提前学 OpenAPI 规范，也不用配 Swagger UI，按顺序走完下面几步，20 分钟内就能在浏览器里点“Try it out”调通接口。
安装与初始化配置
在项目根目录执行：
-
安装包：运行
composer require --dev knuckleswtf/scribe（加--dev是规范做法，文档工具不该进生产环境） -
一键初始化：运行
php artisan scribe:install（新版 v4.10+ 推荐，自动创建config/scribe.php；若用旧版命令vendor:publish --tag=scribe-config，请检查文件是否真实生成） -
关键检查项：打开
config/scribe.php，确认'routes' => ['prefixes' => ['api/*']]已启用——否则所有routes/api.php下的路由都会被跳过
在控制器里写有效注释
Scribe 只读特定标签，其他 PHPDoc 内容（如 @param、@return、@description）全被忽略。重点覆盖三类信息：
-
归属分组：用
@group 用户管理或@subgroup 创建与更新，生成后自动归类 -
参数声明：
- GET 查询参数：
@queryParam page integer optional 默认1 - POST/PUT 请求体：
@bodyParam email string required 邮箱地址，需唯一 - URL 路径变量：
@urlParam id integer required 用户ID
- GET 查询参数：
-
响应示例：提供真实结构 JSON，例如
@response {"id":1,"name":"张三","email":"zhang@example.com"}；如需字段级说明，补@responseField data.name string 用户姓名
生成并正确预览文档
运行生成命令后，文档默认输出到 public/docs，但不能双击打开：
-
生成命令：执行
php artisan scribe:generate；调试时加--force强制刷新缓存 -
正确预览方式：在终端运行
php -S localhost:8000 -t public/docs，然后访问 https://www.php.cn/link/fcbb3a1c04ec11f1506563c26ca63774 —— 直接双击index.html会因浏览器跨域限制白屏 -
认证接口注意：若接口带
auth:sanctum中间件，需在config/scribe.php的'auth' => ['sanctum']中显式声明，否则文档页不会出现 Token 输入框
不复杂但容易忽略。只要确保路由扫描范围对、注释标签写准、预览方式用对，第一份带测试功能的 API 文档就出来了。
