2026年laravel生态中scribe成api文档主流，因其自动感知验证规则、路由与资源转换；swagger-lume因不兼容php 8.1+属性语法、忽略apiresource绑定等缺陷被新项目弃用；scramble以零注解推断契约崛起。
2026年，Laravel官方仍不提供内置API文档生成功能，但生态已明确分化：Scribe成为主流首选，Swagger-Lume基本退出实战舞台。关键不是“哪个更好看”，而是“哪个能让文档真正跟上代码节奏”——Scribe胜在自动感知验证规则、路由结构和资源转换；Swagger-Lume则因无法适配PHP 8.1+属性语法、忽略apiResource隐式绑定、手动维护swagger.php易脱节，已被多数新项目主动弃用。
为什么Swagger-Lume在Laravel 10+中失效
它不是简单“不兼容”，而是底层逻辑与现代Laravel运行机制冲突：
- 依赖传统@OA注解，对PHP 8.1+的#[Validate]、#[MapRequest]等属性语法解析失败，导致参数缺失或类型错判
- 无法识别Route::apiResource()生成的7个标准端点，常漏掉show、destroy等关键接口
- 跳过中间件行为（如auth:sanctum、throttle:api），生成的文档缺少认证头说明和限流提示
- 不读取FormRequest类中的rules()方法，必须重复写@bodyParam，违背DRY原则
- 生成的swagger.json中response结构常为空或仅含"{}"，因未执行控制器逻辑，也未解析Resource::toArray()
Scribe如何做到“文档随代码生长”
它不靠手写OpenAPI定义，而是深度融入Laravel语义层：
- 自动扫描routes/api.php，匹配控制器方法，并提取/** */中的@group、@urlParam、@queryParam等标签
- 读取FormRequest类的rules()和messages()，生成带类型、必填性、错误提示的请求参数表
- 执行控制器方法（可选配置），捕获真实响应体并注入@response示例，避免“大概结构”式描述
- 识别Eloquent Resource类，结合@transformer标签映射toArray()返回字段，精准还原data结构
- 支持Sanctum/Passport自动注入Bearer Token模板，Try-it-out功能开箱可用
Scramble：无注解方案正在改变游戏规则
作为2026年崛起的新锐工具，Scramble不再要求任何PHPDoc注释，直接从代码推断全部契约：
- 从Route::apiResource('posts', PostController::class)自动推导GET /api/posts、POST /api/posts等全部路径及HTTP方法
- 通过分析PostRequest::rules()，得出title:string|required|max:255、content:text|nullable等完整字段定义
- 检查PostResource::toArray()返回值，自动构建响应schema，包括嵌套关系（如author.name）和分页元信息（meta.total）
- 生成标准OpenAPI 3.1.0 YAML，可直连Postman、Redoc或API网关，无需二次转换
- 零配置启动，安装后运行php artisan scramble:generate即完成，适合追求极简协作流程的团队
选型建议：按团队阶段和目标匹配工具
没有绝对优劣，只有是否贴合当前上下文：
- 新项目起步、希望最小学习成本 → 优先试Scramble，尤其适合前后端强协同、拒绝文档滞后场景
- 已有项目大量使用@bodyParam等注释、需快速升级Laravel 10+ → Scribe迁移成本最低，保留原有注释习惯
- 已接入OpenAPI生态（如API网关校验、SDK自动生成）且团队熟悉Swagger规范 → L5-Swagger仍可用，但需严格维护@OA注释
- 仍在用Laravel 8/9且无PHP升级计划 → Swagger-Lume尚可维持，但不建议新项目引入
