Laravel 本身不生成 API 文档，需依赖第三方工具；Scribe 是最省心、维护活跃且原生适配 Laravel 的选择，而 swagger-php + swagger-ui 配置复杂、易出错，不推荐新手使用。
直接说结论：Laravel 本身不生成 API 文档，必须靠第三方工具；Scribe 是当前最省心、维护活跃、原生适配 Laravel 的选择，Swagger（指 swagger-php + swagger-ui）需要手动搭管道、易出错，不推荐新手硬上。
为什么别硬啃 swagger-php + swagger-ui
常见错误现象：GET /api/docs 返回 404、@OA\Get 注解不生效、生成的 openapi.yaml 缺少参数或响应结构、Laravel 的中间件/资源封装被忽略。
-
swagger-php只负责从注解提取定义，不处理路由自动发现，得自己写脚本遍历routes/api.php并映射控制器方法 - Laravel 的
Resource类、FormRequest验证规则、Route::apiResource()的隐式绑定，swagger-php默认完全感知不到 - 要让
swagger-ui正常加载，还得配好静态文件路由、CORS、JSON 响应头，一环断就白忙 - 新版 Laravel（10+）的 PHP 8.1+ 属性语法（如
#[Validate]）和swagger-phpv4 兼容性仍有坑
Scribe 怎么开箱即用
它不是“集成 Swagger”，而是用 Laravel 的语义（路由、验证器、资源类、注释）自动生成 OpenAPI 3.x 文档，并内置 UI。
- 安装：
composer require knuckleswtf/scribe，然后运行php artisan scribe:install - 基础生成：
php artisan scribe:generate—— 它会自动扫描routes/api.php，读取控制器方法上的/** @group Users */、@bodyParam等注释，也识别FormRequest的rules()和Resource的toArray() - 关键配置在
config/scribe.php：'type' => 'static'输出 HTML 文件，'type' => 'laravel'启用内置路由/docs，后者更方便调试 - 想加示例请求体？在控制器方法注释里写：
/** @bodyParam email string required Email address. */，Scribe 会自动填充默认值并校验类型
哪些地方最容易被忽略
文档能跑起来 ≠ 文档可靠。以下三点不检查，上线后前端联调会卡住：
- 中间件影响：如果路由用了
auth:sanctum或自定义 JWT 中间件，scheme必须在config/scribe.php的'auth' => ['sanctum']显式声明，否则 UI 里不会带Authorization头 - 分页响应没写全：Laravel 的
LengthAwarePaginator默认只显示data字段，但 Scribe 不自动推导元信息（links,meta），得手动在响应注释里补：@responseField data[].name string User name+@responseField meta.total integer Total count - 多版本 API 路由冲突：若用了
Route::prefix('v1')但没在scribe.php的'routes' => [...]里指定'prefix' => 'v1'，生成的路径会是/api/users而非/api/v1/users，导致链接 404
真正麻烦的从来不是生成文档，而是让文档和代码行为严格一致——Scribe 的价值在于它把“同步成本”压到了最低，但前提是理解它怎么读你的路由、验证器和资源类。别跳过 php artisan scribe:generate --verbose 看输出日志，那里会告诉你哪条路由被跳过了、哪个参数没解析到。
