scribe通过解析路由、控制器、formrequest和resource并结合结构化注释自动生成api文档：装对（composer安装+artisan初始化）、配准（配置prefixes）、注清（@group/@bodyparam等标签），支持html/ openapi/postman三端输出。
实现“写好接口逻辑即生成文档”，关键在于让文档生成完全依赖代码本身，而不是额外维护一份脱离源码的说明。Scribe 正是围绕这个理念设计的：它不抓包、不运行接口、不靠人工录入，而是从你已写的路由定义、控制器方法、FormRequest 验证规则和 Resource 响应结构中自动提取信息，再结合少量结构化注释，拼出完整、可交互的 API 文档。
装对、配准、注清：三步闭环缺一不可
自动化不是“装完就跑”，而是三个环节严丝合缝：
-
装对：用
composer require --dev knuckleswtf/scribe安装，确保只在开发环境加载；执行php artisan scribe:install初始化配置，避免旧版vendor:publish的路径遗漏风险 -
配准：打开
config/scribe.php，确认'prefixes' => ['api/*']已启用——若只留默认的web组，所有 API 路由都会被跳过 -
注清：控制器方法上方只写 Scribe 识别的标签，如
@group、@bodyParam、@response；其他通用 PHPDoc（如@param、@return）一律不读，写了反而干扰
注释即契约：参数与响应必须显式声明
文档可信的前提，是接口行为在代码里有明确表达。Scribe 不会猜测字段是否必填、类型是否为整数、默认值是多少——这些都得靠注释明说：
-
@queryParam page integer optional 默认1：GET 参数要标清类型、是否必填、默认值和说明 -
@bodyParam email string required 邮箱地址，需唯一：POST/PUT 字段必须带required或optional，不能省略 -
@response {"id": 1, "name": "张三"}：提供真实结构的 JSON 示例，Scribe 会格式化展示并用于 Postman 导出 -
@authenticated：标记需登录接口，文档页自动渲染 Token 输入框，支持 Sanctum/Bearer 流程说明
生成即可用：静态 HTML + OpenAPI + Postman 全覆盖
运行 php artisan scribe:generate 后，文档默认输出到 public/docs，开箱即用：
- 直接通过浏览器访问
/docs，页面自带「Try it out」功能，可实时调用接口（注意中间件兼容性，如 auth 或 throttle 需在配置中临时绕过） - 同时生成标准 OpenAPI 3.0 YAML/JSON 文件，便于接入 API 网关、SDK 自动生成或第三方测试平台
- 导出 Postman 集合，前端可一键导入，省去手动建请求的繁琐
- 支持
--watch模式，在开发时监听文件变化自动重生成，配合 VSCode 集成终端可实现边写边预览
嵌入开发流程：让文档随代码一起演进
文档不是发布前补的作业，而是 MR/PR 中必须审查的一环：
- 在代码评审清单中加入「新增或修改接口是否同步更新了 PHPDoc 注释」
- 通过 GitHub Actions 在
push到 main 分支后自动执行scribe:generate并部署到 GitHub Pages 或 Nginx 目录 - 搭配 FormRequest 类使用，Scribe 会自动读取
rules()中的验证逻辑，减少注释重复 - 返回尽量用 Eloquent Resource 或
response()->json()，配合@response注释，能更准确推断响应结构
