@response 标签通过真实调用并拦截响应（如 JsonResponse 或数组）自动生成准确、可维护的 API 文档示例，需确保路由可达、中间件不阻断，并配合工厂数据与配置过滤敏感字段。
在 Laravel 项目中，用 @response 标签配合 Laravel API 文档工具（如 Scribe）能自动生成真实、可运行的接口响应示例，比手动写 JSON 示例更准确、更易维护。
确保控制器方法返回标准响应结构
@response 能正确抓取响应内容的前提，是目标路由对应的方法必须实际执行并返回一个有效的 Illuminate\Http\JsonResponse 或数组。它不是模拟数据，而是“真实调用 + 拦截响应”。
- 避免在文档注释里写
@response {"error": "not found"}这类静态字符串——这会绕过 Scribe 的自动捕获机制 - 确保该接口在当前环境（如
local或testing）下可访问，且无中间件（如权限校验）阻断请求 - 若需展示错误响应，建议专门定义一条测试路由或临时关闭 auth 中间件，让 Scribe 能真实触发异常并捕获 401/422 等状态码和 body
在 PHPDoc 中正确使用 @response 标签
只需在控制器方法上方添加 @response，不带参数即可启用自动响应捕获；也可指定 HTTP 状态码或自定义响应键名。
-
@response—— 默认捕获 200 响应 -
@response status=422—— 指示 Scribe 执行一次触发验证失败的请求（例如提交空表单） -
@response scenario="with relations"—— 配合 Scribe 的自定义场景，在测试中预设数据关系再响应
注意：这些标签必须写在方法的 PHPDoc 注释块内，且紧邻方法声明上方。
配合测试数据工厂提升响应真实性
Scribe 在生成响应时会运行实际请求，因此数据库中需有对应测试数据。推荐结合 Laravel 的模型工厂与数据库迁移快照。
- 在
routes/api.php或测试专用路由中，为文档接口添加“测试友好”的前置逻辑，比如User::factory()->create(['email' => 'api@example.com']) - 使用
php artisan scribe:generate --force时，Scribe 会清空并重建测试数据库（若配置了database.connections.testing） - 对软删除、时间戳、访问权限等细节敏感的接口，务必在工厂中显式设置字段，否则响应可能缺失关键字段
定制响应内容：跳过敏感字段或注入动态值
真实响应中常含 created_at、updated_at、token、ID 等不宜固化在文档里的字段。可通过 Scribe 配置过滤或替换。
- 在
config/scribe.php的responses部分设置'exclude' => ['id', 'token', 'pivot'] - 用
@transformer关联自定义 Transformer 类，对响应做字段重命名、格式化或脱敏处理 - 在响应数组中使用
now()或Str::random(16)等动态值，Scribe 会保留其执行结果而非字面量
不复杂但容易忽略：@response 不是装饰性注释，它是文档自动化流程中的“执行锚点”。写对位置、配好数据、理清上下文，就能让接口文档始终与代码行为同步。
