laravel 10+ 官方不生成 api 文档，swagger-lume 因不兼容 php 8.1+ 属性语法、无法识别 apiresource/中间件/resource 封装而失效；首选 knuckleswtf/scribe，它自动扫描路由、formrequest 规则及 @bodyparam 等注释，开箱生成带 try-it-out 的交互式 openapi 文档。
Laravel 10+ 官方不生成 API 文档，Swagger-Lume 已不推荐使用，主要因其依赖手写注释、对 PHP 8.1+ 属性语法支持弱、路由自动发现能力差。当前最实用的替代方案是 knuckleswtf/scribe，它能基于控制器逻辑、FormRequest 验证规则和少量结构化注释，自动生成可交互的 OpenAPI 文档。
为什么 Swagger-Lume 在 Laravel 10+ 中失效
Swagger-Lume 的底层依赖注解解析（如 @OA\Get），但 Laravel 10+ 默认启用 PHP 8.1+ 属性语法（如 #[Validate]），而 Swagger-Lume 对这类新语法兼容性差；同时它无法识别 Route::apiResource() 的隐式绑定、Eloquent Resource 封装或中间件行为，导致生成的文档参数缺失、响应结构错乱，甚至出现 404。
- 手动维护
swagger.php文件，与实际代码易脱节 - 不感知 FormRequest 的验证规则，需重复写
@bodyParam - 无法处理 Laravel 的服务容器绑定、中间件跳过逻辑等运行时行为
Scribe 是 Laravel 10+ 的首选替代方案
Scribe 直接扫描控制器方法签名、请求类（FormRequest）、返回类型提示及注释标签（如 @group、@response），无需额外配置即可输出结构准确、带示例请求/响应的文档页面。
- 开箱支持 Laravel 10+ 和 PHP 8.1+ 属性语法，无需降级兼容
- 自动提取
rules()方法中的字段定义，生成完整的请求参数表 - 支持
@transformer标签，精准映射 Eloquent Resource 输出结构 - 生成的文档默认含 Try-it-out 功能，支持 Bearer Token 认证调试
快速接入 Scribe 的关键步骤
安装后只需三步即可启用，不需修改现有路由或控制器结构：
- 执行
composer require --dev knuckleswtf/scribe - 运行
php artisan scribe:generate，Scribe 自动扫描routes/api.php及对应控制器 - 访问
/docs（开发环境）查看交互式文档；生产环境可导出为静态 HTML 或 OpenAPI JSON
若需中文支持，可在配置中设置 'default_language' => 'zh'，并为注释标签补充中文描述，如 @bodyParam name string required 用户姓名。
其他轻量备选：OpenAPI 原生集成思路
如果你倾向更底层、零第三方包的方案，Laravel 本身虽无内置文档生成器，但可通过组合方式实现最小闭环：
- 用
Route::get('/openapi.json', [...])手动构造 OpenAPI 3.0 JSON（适合接口极少的项目） - 借助 Laravel 的
Route::getRoutes()+ 反射获取控制器方法，自行提取注释与类型信息（需维护） - 搭配前端 Scalar（类似 Swagger UI 替代品）渲染本地 JSON，避免 Swagger UI 的 CORS 和路由问题
这种方式自由度高，但投入产出比低，仅建议极简场景或学习用途。
