Scribe生成Laravel API文档时，中间件禁用和路由组配置是关键开关：需关闭内核反射（'use_kernel_for_middleware' => false）、显式配置路由前缀（如'api/*'）并手动注册RequestContextStrategy，否则文档将空白或缺失认证标识。
用 Scribe 生成 Laravel API 文档时，中间件禁用和路由组配置不是可选项，而是决定“哪些接口能被扫到、哪些权限信息能显示出来”的关键开关。配错会导致文档空白、分组丢失、认证标识不出现，甚至整个 API 列表直接消失。
为什么中间件配置会直接影响文档生成
Scribe 默认尝试从 app/Http/Kernel.php 反射中间件链，用来标注每个接口所属的中间件组（比如 api、auth:sanctum）。但在 Laravel 11 中，Kernel.php 已被移除或弃用，继续依赖它就会导致：
- 所有路由被识别为无中间件，
@group api标签失效 -
@authenticated注释不渲染锁图标，也不提示需认证 - 路由扫描结果为空或只显示部分接口
解决办法很明确：关掉反射，手动告诉 Scribe 你用了哪些中间件组。
在 config/scribe.php 中设置：
再确认 'routes' 配置里已显式声明匹配规则，例如：
['match' => ['prefix' => 'api']]- 或多版本：
['match' => ['prefix' => 'api/v1']]
路由组配置：别让 Scribe “看不见”你的 API
Scribe 不会自动加载 routes/api.php，除非你明说。它默认只认 web 中间件组下的路由——而绝大多数 API 都走 api 组，这就天然被跳过。
必须在 config/scribe.php 的 'routes' 项中写死前缀匹配：
- 确保包含
'prefixes' => ['api/*']或更精确的['api/v1', 'api/v2'] - 如果用了自定义域名或子域，补充
'domains' => ['api.example.com'] - 想只文档化某几个接口？用
'include'明确列出名称或路径，如'users.store'或'POST /posts'
改完记得运行 php artisan scribe:generate --dry-run 看输出列表是否包含你预期的路由。
控制器方法上要加注释，不是加中间件
很多人误以为“给路由加了 ->middleware('auth:sanctum')，Scribe 就会自动标出需认证”。其实不会。Scribe 只读控制器方法上方的 PHPDoc，不解析路由定义里的中间件调用。
要让认证状态出现在文档里，得两步走：
- 在方法注释里写
@authenticated - 确保已注册
RequestContextStrategy（Laravel 11 必须手动注册）
策略注册放在 bootstrap/app.php 文件末尾，例如：
没这行，@authenticated 就是摆设，连 warning 都不报。
本地预览前，先确认中间件和路由都“活”着
生成文档后，别急着双击 index.html。那会白屏，因为 JS 加载失败——这不是 Scribe 的问题，是浏览器限制。
正确做法是启动 PHP 内置服务器：
php -S localhost:8000 -t public/docs然后访问 http://localhost:8000。这时看到的文档，才是真实反映你当前中间件配置和路由分组的结果。如果页面里没有分组标题、没有锁图标、参数全是 unknown，就说明上面三步至少有一处没到位。
