选对文档工具比写好注释更关键：SCRIBE适合快速迭代团队，L5-Swagger适配OpenAPI生态，Scramble追求零维护，laravel-apidoc-generator适合稳定老项目。
选对文档工具，比写好注释更关键。Laravel生态里没有“万能方案”，只有适配项目节奏和团队习惯的工具——核心差异不在功能多寡，而在它怎么跟你的代码一起呼吸。
SCRIBE：适合快速迭代、讨厌注解负担的团队
Scribe（knuckleswtf/scribe）是当前 Laravel 社区最活跃的文档生成器，主打“少写注释、多靠推断”。它自动扫描路由、读取 FormRequest 验证规则、解析 API Resource 结构，连中间件分组和模型绑定都能识别。
- ✅ 优势明显：安装即用（
composer require --dev knuckleswtf/scribe），支持 HTML / OpenAPI 3.0 / Postman 三格式导出；不强制 OpenAPI 注解语法，用@bodyParam、@response这类贴近 PHP 习惯的标签即可控制输出 - ⚠️ 注意点：Laravel 11 中需调整策略注册时机——必须在
bootstrap/app.php的服务注册阶段挂载RequestContextStrategy，否则@authenticated标签会失效；旧版 Kernel.php 若残留，可能干扰中间件识别 - ? 适用场景：API 变动频繁、团队倾向“写完接口就跑文档”的中小型项目，尤其适合 Laravel 9/10/11
L5-Swagger：对接 OpenAPI 生态、需要强规范协作的项目
L5-Swagger（darkaonline/l5-swagger）仍是企业级项目首选，尤其当团队已接入 Swagger UI、Postman 工作流或有第三方平台对接需求时。它严格遵循 OpenAPI 3.0 规范，文档即契约。
- ✅ 优势明显：生成的 JSON/YAML 可直接被 CI/CD 流程消费，也兼容 Redoc、Stoplight 等下游工具；注解即标准，利于前后端对齐接口定义
- ⚠️ 注意点：必须手写完整
@OA\Get、@OA\RequestBody等注解，学习成本高；若控制器方法没加注解，该接口就不出现在文档里；升级 Laravel 11 后需检查paths.annotations是否覆盖新目录结构 - ? 适用场景：中大型项目、已有 OpenAPI 协作流程、需与外部系统（如网关、测试平台）深度集成
Scramble：追求零维护、代码即文档的极简主义者
Scramble 是真正意义上的“无注解方案”——不依赖任何 PHPDoc，直接从路由定义、控制器逻辑、验证规则和响应构造中提取元数据。文档随代码编译而更新，无需人工干预。
- ✅ 优势明显：零配置起步，运行命令即生成；响应结构自动推导（包括嵌套资源、条件返回）、参数类型自动识别（如
int、string|null）；支持实时沙箱执行示例代码块 - ⚠️ 注意点：对自定义响应构造（如手动 new JsonResponse）支持有限；复杂中间件逻辑或动态路由（如闭包路由）可能漏解析；暂未原生支持多版本 API 并行文档
- ? 适用场景：强调开发速度、文档一致性优先于精细控制的初创团队，或已采用 Laravel 13 多模态文档引擎的项目
Laravel-apidoc-generator：稳定老将，适合熟悉传统工作流的团队
这个老牌工具（mpociot/laravel-apidoc-generator）仍被大量 Laravel 5.7–10 项目使用，特点是成熟、可预测、配置粒度细。
- ✅ 优势明显：路由匹配规则灵活（支持 domain/prefix/version 多维过滤）；支持静态 HTML 输出到
/public/docs，部署简单；控制器级@group和方法级@subgroup分组逻辑清晰 - ⚠️ 注意点：已停止主版本更新，对 Laravel 11+ 的中间件反射机制适配不佳；生成器不处理 Eloquent 关系自动展开，需手动补
@responseField - ? 适用场景：存量 Laravel 9 或更早项目维护、不急于升级文档体验、重视部署确定性的团队
