Scribe比传统Swagger更适合Laravel，核心在于它不是“套用OpenAPI标准”，而是“理解Laravel本身”——自动读取路由定义、FormRequest验证规则、Resource响应结构和中间件逻辑，生成的文档天然贴合框架行为，不靠手写注解堆砌，也不因PHP 8.1+属性语法或apiResource隐式绑定而失效。
自动扫描Laravel原生结构，不依赖人工注释
Scribe直接解析控制器方法签名、绑定的FormRequest类、返回类型提示（如UserResource::make()）、甚至中间件跳过逻辑。它不需要你反复在代码里写@OA\Get或@bodyParam，更不会因PHP 8.1+的#[Validate]属性而漏掉验证字段。Swagger-php则必须手动补全所有@OA注解，稍有遗漏，参数就消失或类型错乱。
- Route::apiResource('posts', PostController::class) → 自动识别全部7个REST动作及对应请求/响应
- store(Request $request)中注入StorePostRequest → 自动提取全部required/string/email等规则并转为文档参数
- return PostResource::collection($posts) → 推断出分页结构、data数组、每个post字段类型与示例
生成即用型交互文档，无需额外部署管道
Scribe默认输出静态HTML页面（public/docs/index.html），开箱支持“Try it out”功能，自动携带Bearer Token、填充表单、显示真实响应。它导出的OpenAPI 3.0 JSON可直供Postman导入或API网关接入，不需要像Swagger-ui那样单独配Nginx路由、维护swagger.json路径或调试CORS问题。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 执行php artisan scribe:generate后，访问/docs即可在线调试接口
- Token认证说明自动出现在每个需要鉴权的接口页，无需重复写@authenticated
- 错误响应（如422校验失败）也能从FormRequest的messages()中提取示例，不是空泛的“Bad Request”
无缝嵌入开发流程，避免文档与代码脱节
Scribe能自然融入CI/CD：在GitHub Actions中监听main分支合并，自动运行scribe:generate并推送至GitHub Pages或内部Nginx目录。它不强制要求PR中提交swagger.yaml变更，也不因某次忘记更新注释导致线上文档失真——文档随代码一起构建，而不是靠人肉同步。
- MR/PR阶段只需检查控制器注释是否清晰（如@group、@response），而非整套OpenAPI语法
- 配置文件config/scribe.php可设置仅扫描app/Http/Controllers/Api目录，排除测试或管理接口
- 支持中文字段名、多语言响应示例，不用额外改locale或hack模板
轻量稳定，适配Laravel 10+主流生态
相比已停更的Swagger-Lume，或需深度定制的swagger-php + swagger-ui组合，Scribe由Laravel社区活跃维护（knuckleswtf组织），对Laravel 10+、PHP 8.2、Livewire、Inertia等现代栈兼容良好。它不侵入路由注册、不替换服务容器绑定，安装即用，故障时排查路径清晰——报错通常指向具体控制器或Request类，而非抽象的注解解析器。
- 安装仅需一条命令：composer require --dev knuckleswtf/scribe
- 发布配置：php artisan scribe:install，无须修改autoload或手动注册服务提供者
- 不强制使用@response标签——若未提供，Scribe会尝试从实际API响应中抓取结构（需开启"laravel_api_tester"配置）
