Scribe为Laravel生成专业API文档的关键是装对包、配好config、注准接口；需用--dev安装、确认routes包含api/*、仅用@group/@bodyParam等特定标签注释，并通过PHP内置服务器预览。
想用 Scribe 为 Laravel 项目快速生成专业 API 文档，关键不是堆功能，而是走对三步：装对包、配好 config、注准接口。新手最容易卡在安装后看不到路由、注释写了却不生效、本地打不开文档页面——其实问题都出在这三个环节的细节上。
安装 Scribe 包要加 --dev 标志
Scribe 是开发阶段工具，不该进入生产环境。直接在项目根目录运行：
- composer require --dev knuckleswtf/scribe
别漏掉 --dev。如果误用 composer require knuckleswtf/scribe（不带 --dev），它会被写进 require 而非 require-dev，后续部署时可能意外加载，还容易引发混淆。
配置文件生成推荐用 scribe:install 命令
新版 Scribe（v4.10+）已统一初始化流程，比 vendor:publish 更直接：
- php artisan scribe:install
这条命令会自动创建 config/scribe.php，并预设常用选项。如果你执行的是旧版教程里的 vendor:publish --tag=scribe-config，也能用，但要注意检查是否真的生成了文件——有时因缓存或权限问题会静默失败。生成后务必打开 config/scribe.php，确认 'routes' => ['prefixes' => ['api/*']] 已启用，否则所有 API 路由都会被跳过。
注释必须用 Scribe 认的标签，其他一概忽略
PHPDoc 里写再多说明也没用，Scribe 只识别特定标签。常见有效标签有：
- @group 用户管理 —— 给接口分组，文档自动归类
- @queryParam page integer optional 默认1 —— GET 参数，类型、必填性、默认值、说明缺一不可
-
@bodyParam email string required 邮箱地址 —— POST/PUT 请求体字段，
required或optional必须明确写出 - @response {"id":1,"name":"张三"} —— 提供真实结构的 JSON 示例，Scribe 会格式化展示
像 @param、@return、@description 这类通用标签，Scribe 完全不读，写了反而干扰阅读。
生成后不能双击 index.html 查看
运行 php artisan scribe:generate 后，文档默认输出到 public/docs。但直接双击 public/docs/index.html 会白屏——因为浏览器跨域限制导致 JS 加载失败。
正确预览方式是启动 PHP 内置服务器：
- php -S localhost:8000 -t public/docs
然后访问 http://localhost:8000 即可正常交互。调试阶段可加 --force 强制刷新：php artisan scribe:generate --force。
