Laravel API 文档应精简注释，仅用 Scribe 识别的 @bodyParam、@queryParam、@response 标签，结合 FormRequest 验证规则自动推导参数，并配置路由扫描与中文支持。
跳过冗余注释、直接生成高质量 Laravel API 文档，核心在于“用代码结构说话，让工具自动理解”，而不是靠人写满 PHPDoc。关键不是少写注释，而是只写 Scribe 真正需要的那几行——它不读 @param/@return，只认 @bodyParam、@queryParam、@response 这类语义明确的标签。
只写 Scribe 能识别的注释，其他一律省略
Scribe 不解析通用 PHPDoc，大量 @param 或 @return 反而干扰解析。真正起作用的只有以下三类：
-
@bodyParam：用于 POST/PUT 请求体字段，必须标明类型、是否必填、示例值（如
@bodyParam name string required 示例: 李四） -
@queryParam：用于 GET 查询参数，支持默认值标注（如
@queryParam per_page integer 默认: 10） -
@response：提供真实 JSON 结构示例，Scribe 会据此推导字段类型和说明（如
@response { "id": 1, "email": "user@example.com" }）
让验证逻辑代替注释描述参数
FormRequest 类或 $request->validate() 中的规则，Scribe 会自动提取并补全参数说明。例如：
- 写
'email' => 'required|email|unique:users'，Scribe 就能标出 email 是 string、required、格式为邮箱 - 写
'avatar' => 'file|mimes:jpg,png|max:2048'，它就能识别为 file 类型、带限制说明 - 不用再手动加
@bodyParam avatar file required—— 验证规则已足够
配置精准路由扫描，避免“找不到接口”
默认情况下 Scribe 只扫描 web 中间件组，API 路由常被跳过。必须在 config/scribe.php 显式声明：
-
'routes' => [['match' => ['prefix' => 'api']]]—— 确保匹配所有api/xxx路由 -
'auth' => ['sanctum']（不是auth:sanctum）—— 中间件名需与app/Http/Kernel.php中注册名完全一致 - 若用
Route::apiResource()，需在路由定义上方加/** @group 用户管理 */，否则分组丢失
中文支持与开发体验优化
中文文档可直接生效，无需额外插件：
- 注释中的中文说明（如
@bodyParam name string required 用户姓名）会原样显示在生成页 - 在
config/scribe.php中设置'example_languages' => ['bash', 'javascript', 'php']，方便前端调用参考 - 加
--watch参数启动实时监听：php artisan scribe:generate --watch，保存控制器后自动刷新文档
