Laravel 11 路由变更导致文档生成器失效，主因是 routes.php 成为唯一入口但旧生成器不识别、闭包路由无法静态分析、中间件组需在 bootstrap/app.php 显式注册、分组语义更严格且响应须经 response()->json() 返回。
Laravel 11 的路由定义方式变化，直接动摇了 API 文档生成器的“感知基础”——不是注解写错了，而是生成器根本找不到路由、读不到中间件、也推不出认证状态。关键问题集中在路径加载、分组语义和闭包限制三处。
routes.php 成为唯一入口，但文档生成器默认不认它
旧版生成器（如 scribe、apidoc-generator）习惯扫描 routes/api.php 或 routes/web.php，而 Laravel 11 默认只加载 routes.php，且不再自动引入子文件。若你保留 api.php 却没在 routes.php 中显式 require，那整个 API 路由块就对生成器“隐身”了。
- 确保所有 API 路由最终都经由
routes.php加载，例如：Route::middleware('api')->group(function () { require __DIR__.'/api.php'; }); - 在
config/apidoc.php的'routes' => []配置中，明确列出实际路径：base_path('routes.php')和base_path('routes/api.php') - 避免用闭包写路由（
Route::get('/', fn() => ...)），这类代码无法被静态分析捕获，注解直接失效
中间件组不再隐式存在，@authenticated 注解失去上下文
Laravel 11 移除了 app/Http/Kernel.php，中间件组必须在 bootstrap/app.php 中通过 $middleware->api() 显式声明。文档生成器依赖这个组名来识别“哪些路由需要登录”，如果没注册 api 组，或没把认证中间件（如 EnsureTokenIsValid）追加进去，@authenticated 就成摆设。
- 检查
bootstrap/app.php是否包含类似代码：->withMiddleware(function (Middleware $middleware) { $middleware->api(append: [EnsureTokenIsValid::class]); }) - 控制器方法的 PHPDoc 必须显式写
@authenticated，不能指望生成器“猜”中间件意图 - 若用 Sanctum 或其他守卫，还需在
config/apidoc.php的'auth' => []中补全配置，否则示例请求不会带 token
路由分组语义变更，name() 和 prefix() 行为更严格
虽然 Route::name() 和 Route::prefix() 本身没删，但 Laravel 11 要求它们必须包裹在明确的中间件分组内（如 Route::middleware('api')->group()），否则生成器可能无法关联路由到正确的认证上下文或版本前缀。
- 命名路由必须链式调用
->name('xxx')，分组前缀需配合Route::name('v1.')->group(...)才能生成层级名（如v1.users.index） - API 资源路由请坚持用
Route::apiResource()，别混用Route::resource()——后者会套 web 中间件，导致 CSRF 拦截，文档里显示的请求却始终 419 - 使用
Route::prefix('api/v1')时，注解里的@OA\Get(path="/users")不要写成/api/v1/users，否则 Swagger UI 会拼出双倍前缀
响应结构提取逻辑升级，裸数组返回不再被识别
Laravel 11 的文档生成策略默认要求响应经过 ResponseFactory 构造。直接 return ['data' => $user] 在 Laravel 9/10 还能被反射提取字段，但在 11 中会被跳过，导致 @responseField 失效、示例 JSON 空白。
- 控制器方法统一改用
return response()->json(['data' => $user]); - 若用
ApiResource，确保@apiResource注解指向的类已正确定义toArray()或$casts，避免字段推断偏差 - 时间戳字段（
created_at/updated_at）因迁移中新增->default(now())，部分工具会误判为“必填”，建议在注解中用@OA\Property(nullable=true)显式说明
