laravel 11 中 scribe 需调整策略注册、禁用 kernel 中间件反射、强制使用 response()->json() 返回响应，并适配 withrouting 路由加载方式。
在 Laravel 11 中使用 Scribe 生成 API 文档，不能直接沿用 Laravel 9 或 10 的配置方式。核心变动不在注释语法，而在于 Scribe 如何感知路由上下文、中间件状态和响应构造逻辑——这些都因 Laravel 11 启动机制重构而失效。
策略注册必须移至 bootstrap/app.php 的服务绑定阶段
Laravel 11 要求部分文档策略（尤其是依赖请求生命周期的）必须在应用启动早期动态注册，而非靠 config/apidoc.php 静态加载。
- 删除或注释掉 config/apidoc.php 中的
strategies数组，它在 Laravel 11 下不再被读取 - 在
bootstrap/app.php的->withProviders()或->withMiddleware()之后，手动注册策略类，例如：Scribe::extend('request-context', \App\Documentation\Strategies\RequestContextStrategy::class); - 若使用
@authenticated或@middleware标签但未挂载RequestContextStrategy，文档中将完全不显示认证标识，且无任何报错提示
中间件信息提取需绕过已废弃的 Kernel.php
Laravel 11 彻底移除了 app/Http/Kernel.php 中的中间件数组声明，而 Scribe 默认仍尝试反射该文件获取中间件链——这会导致分组标签（如 @group api）失效或权限推断为空。
- 确认项目中已删除
app/Http/Kernel.php文件（即使保留也请确保不被引用） - 在
config/apidoc.php中显式设置：'use_kernel_for_middleware' => false - 运行
php artisan scribe:generate --dry-run，检查输出是否列出你预期的中间件（如api,web,auth:sanctum）
响应结构提取强制依赖 ResponseFactory 构造
Scribe 在 Laravel 11 中默认启用 Schema 推导，但仅识别经由 response()->json() 等工厂方法返回的响应；裸数组返回（如 return ['data' => $user];）将跳过字段解析，导致 @responseField 注释无效。
- 控制器中所有需要文档化的 JSON 响应，必须显式调用响应工厂：
return response()->json(['data' => $user], 200); - 若使用资源类（Resource），确保其
toArray()返回后仍被包裹进response()->json() - 验证方式：在路由闭包或控制器方法中临时加入一个
response()->json(['test' => 'ok'])，观察生成文档中是否出现该结构字段
路由加载路径需与 Laravel 11 的 withRouting 行为对齐
Laravel 11 的 ->withRouting() 默认只加载 routes.php，不再自动合并 routes/api.php 或 routes/web.php。若仍按旧习惯拆分路由文件，Scribe 将无法扫描到其中定义的接口。
- 要么统一迁移到单文件
routes.php - 要么在
bootstrap/app.php中手动加载并显式绑定中间件组：require base_path('routes/api.php');Route::middleware('api')->group(function () { require base_path('routes/api.php'); }); - 确保 Scribe 的
routes配置项中包含对应文件路径，例如：'routes' => [['match' => ['prefixes' => ['api/*']]]]
