Laravel需借助knuckleswtf/scribe实现自动化API文档生成，其通过解析控制器、验证规则和注释标签（如@bodyParam、@queryParam、@response）生成可交互文档，优于swagger-lume；配置时需注意中间件禁用、中文支持及注释规范。
Laravel 本身不内置 API 文档生成功能，但通过 darkaonline/swagger-lume（轻量、Laravel 5.5+ 兼容）或更现代的 knuckleswtf/scribe，可以真正实现「写好接口逻辑 + 少量注释 → 自动生成可交互文档」。关键不是“能不能”，而是选对工具、避开注释冗余和路由扫描失效这两个坑。
用 scribe 替代 swagger-lume 更省心
swagger-lume 依赖手写 swagger.php 注释，且对 Laravel 10+ 的 PHP 8.1+ 属性语法支持弱；scribe 直接解析控制器方法、请求验证规则和返回示例，开箱即用。
- 安装：
composer require --dev knuckleswtf/scribe
- 发布配置：
php artisan scribe:install
- 生成文档：
php artisan scribe:generate
—— 默认输出到public/docs，打开public/docs/index.html即可浏览 - 它会自动识别
request()中的FormRequest类、@bodyParam注释、@response示例，不需要写完整 OpenAPI YAML
控制器里怎么写注释才被 scribe 正确提取
注释不是越多越好，scribe 只认特定标签，其他会被忽略。重点写清参数来源、必填性、示例值。
-
@bodyParam用于 POST/PUT 请求体字段：/** * 创建用户 * @bodyParam name string required 用户姓名 * @bodyParam email string required 邮箱，必须唯一 * @bodyParam avatar file optional 头像文件 */
-
@queryParam用于 GET 查询参数：/** * 获取用户列表 * @queryParam page integer 是否分页，默认 1 * @queryParam per_page integer 每页数量，默认 15 */
- 返回响应建议用
@response提供真实结构：@response { "id": 1, "name": "张三", "email": "zhang@example.com" } - 避免写
@param或@return—— scribe 不读这些，纯属干扰
生成后接口测试失败？检查中间件和路由组
scribe:generate 是在 CLI 环境下运行的，不会加载 session、auth 或跨域中间件。如果接口加了 auth:sanctum 或 throttle，文档页里「Try it out」会 401 或 429。
- 临时禁用敏感中间件：在
config/scribe.php的middleware数组中移除auth、throttle等项 - 确保 API 路由定义在
routes/api.php，且未被Route::middleware('web')包裹 —— web 中间件会触发 session 启动，导致 CLI 下报错 - 若用 Sanctum，需在
config/sanctum.php中设置'stateful' => []，或为文档域名（如docs.test）加入白名单
如何让文档支持中文、自定义标题和排序
默认生成的文档是英文，且接口按路由注册顺序排列，不一定是业务逻辑顺序。
- 改语言：编辑
config/scribe.php，把'language' => 'en'改成'zh'，并确保已发布本地化文件：php artisan vendor:publish --tag=scribe-translations
- 改标题/描述：在
config/scribe.php的'title'和'description'字段直接填写中文字符串 - 控制顺序：给每个控制器方法加
@group 用户管理、@subgroup 创建与更新，生成后自动分组折叠，比手动排序更可持续 - 去掉无意义的健康检查接口：在
config/scribe.php的'include' => []中明确列出要包含的控制器，别用scan模式扫全项目
实际项目里最常卡住的，是以为「写了注释就等于文档可用」，结果发现 @bodyParam 拼错成 @body_param，或漏了 required 导致字段被忽略。生成前先跑一次
php artisan scribe:generate --dry-run，看控制台输出是否列出了你预期的接口，比打开 HTML 页面再调试快得多。
