精准控制Laravel Scribe文档元数据需配置title（如“订单中心 API 文档”）、description（含调用约束）、base_url（如env('APP_URL').'/api'）、routes（prefixes/exclude控制可见性）、auth（显式声明鉴权方式）及type（static或laravel决定交互能力）。
要在 Laravel 中通过 config/scribe.php 精准控制文档元数据，关键不是改完就完事，而是让标题、描述、URL、分组逻辑等真正贴合项目语义和团队协作习惯。配置生效的前提是理解每个字段的用途与影响范围。
基础元数据：标题、描述与基础 URL
这三个字段直接出现在文档首页顶部、OpenAPI 规范根节点及 Postman 集合元信息中，影响第一印象和外部系统集成。
-
title：建议使用业务名称而非“API Documentation”，例如
'title' => '订单中心 API 文档'，避免泛化 -
description：不只是功能罗列，可补充适用对象或约束，如
'description' => '面向内部运营系统调用，需携带 X-App-ID 请求头' -
base_url：务必与实际部署环境一致。若 API 前缀为
/api，应设为env('APP_URL') . '/api'（非config('app.url')），否则请求示例中的路径会多一层嵌套
路由分组与可见性控制
元数据不只是“写什么”，更是“对谁展示什么”。routes 配置决定哪些接口进入文档，本质是文档的权限边界。
- 用
prefixes锁定主干，如['api/v1/*', 'api/v2/*']，避免意外包含测试路由 -
include适合明确指定高优先级接口，例如['orders.index', 'POST /webhooks/stripe']，支持命名路由或原始路径混用 -
exclude推荐用于排除敏感或临时接口，如['GET /debug/*', 'admin.*']；注意通配符匹配基于 Laravel 路由注册名，不是 URL
认证与安全元信息注入
当 API 含 Sanctum、Passport 或自定义 token 验证时，仅靠中间件标记不够，需在元数据层显式声明，否则文档中“Authentication”区块为空或错误。
立即学习“PHP免费学习笔记（深入）”；
- 设置
'auth' => ['enabled' => true]是前提，再补全细节：'in' => 'bearer'（位置）、'name' => 'Authorization'（Header 名） - 若使用请求头以外的方式（如 query 参数
api_token），需同步配置'in' => 'query'和'name' => 'api_token' - 配合控制器注解
@authenticated使用，Scribe 才会为该接口自动渲染鉴权说明与示例请求头
输出类型与交互能力元配置
type 不只是格式选择，它决定了文档是否能响应真实请求、是否支持前端调试、是否兼容 CI 流水线。
-
'type' => 'static'：生成纯 HTML，适合部署到 Nginx/Apache，但无法执行真实 API 调用（无 CSRF Token、无 Session） -
'type' => 'laravel'：走 Blade 渲染，支持Route::middleware('auth:sanctum')自动识别，并启用浏览器内请求（需 Laravel APP_KEY 和 session 配置正常） - 若需 OpenAPI 3.0 文件供第三方平台导入，保留
'openapi' => true并确保'type'为static或laravel，生成时会自动产出openapi.yaml
