Scribe 是 Laravel API 文档关键基础设施，自动从注释和验证规则生成带类型、必填标识、示例及真实响应的交互式文档，集成“Try It Out”测试、支持 OpenAPI 导出、随代码实时更新，并深度适配 Sanctum/Passport。
用 Scribe 生成的 Laravel API 文档，不是“锦上添花”，而是前后端协作中真正能减少扯皮、加速联调、降低出错率的关键基础设施。
让前端不猜参数，也不再反复问“这个字段是必填吗”
传统协作中，后端写完接口，靠口头或零散 Markdown 说明请求结构，前端常因参数类型、是否可选、默认值、示例值不明确而反复确认。Scribe 把这些信息从代码注释和 FormRequest 验证规则里自动提取出来，生成带类型标注、必填标识、示例值（甚至真实响应）的文档页。前端拿到的就是一份“可执行说明书”，直接照着写 Axios 请求或封装 Hook，省去大量沟通成本。
- @queryParam page integer 可选，默认1 → 前端知道可以不传，也清楚该传数字
- @bodyParam avatar file 必填，MIME 类型：image/* → 上传组件逻辑一次写对
- @response 200 自动运行控制器并截图返回体 → 看到的是真实结构，不是“大概长这样”
把 Postman 测试集成进文档页面，“试一试”按钮点一下就发请求
Scribe 生成的 HTML 文档内置 “Try It Out” 功能，前端或测试人员无需打开 Postman，就在浏览器里填参数、选认证方式（如 Bearer Token）、点击发送，立刻看到响应状态码和 JSON 数据。这不仅加快了接口验证速度，还让问题定位更直观——如果前端调不通，先在文档页试一遍，能快速判断是前端代码问题，还是后端逻辑/配置/权限问题。
- 支持自动注入 Sanctum 或 Passport 的 token 模板，登录后一键复用
- 请求头、查询参数、Body 表单都可视化编辑，避免手动拼 URL 出错
- 响应结果高亮显示，错误信息（如 422 校验失败）原样呈现，便于调试
文档随代码更新，不再出现“文档写了但接口已改”的尴尬
手动维护文档最大的痛点是脱节。Scribe 将文档生成纳入开发闭环：每次提交前跑 php artisan scribe:generate，或接入 CI/CD 流程自动触发，确保 public/docs 下的文档永远反映当前分支的真实接口。新成员入职，看文档就能准确理解所有可用端点；重构接口时，改完代码顺手更新注释，文档就同步刷新。这种“代码即文档”的一致性，极大减少了因信息滞后导致的协作阻塞。
- 配合路由筛选（如只包含
api/*），避免把内部调试路由暴露出去 - 启用缓存（
--cache）后，大型项目生成时间大幅缩短，不影响日常开发节奏 - 导出 OpenAPI 文件可被前端工具链消费，比如自动生成 TypeScript 接口定义或 Mock 服务
不只是给前端看，更是团队知识沉淀的起点
一份结构清晰、交互可用的文档，天然成为新老成员快速上手项目的入口。它比代码注释更易读，比 Swagger UI 更贴合 Laravel 生态，还能嵌入业务说明（如“此接口仅限运营后台调用”）。当文档部署在内网或 GitHub Pages 上，它就不再是临时产物，而是持续演进的系统契约。后端自测、QA 编写用例、产品核对功能边界，都能从中获取权威依据。
- 支持分组（group）和排序，按模块（用户、订单、支付）组织接口，逻辑更清晰
- 可静态部署，不依赖 PHP 运行环境，方便嵌入企业知识库或 Confluence
- 与 Laravel Sanctum / Passport 深度集成，鉴权流程在文档中一目了然
