Laravel API PHPDoc注释需按请求方法规范编写：GET用@OA\Get标注查询参数；POST用@OA\Post定义请求体；PUT用@OA\Put确保全量字段；DELETE用@OA\Delete说明路径参数与响应语义。
在 Laravel 项目中，为 API 接口编写清晰、标准的 PHPDoc 注释，不仅能提升团队协作效率，还能为自动生成文档（如使用 @OA\Get 配合 Swagger / OpenAPI）提供准确依据。针对 GET / POST / PUT / DELETE 四类核心请求方法，注释需明确标注请求路径、参数类型与位置、请求体结构、响应内容及可能的状态码。
一、GET 请求：强调查询参数与响应结构
GET 用于获取资源，参数应全部通过 URL 查询字符串传递，不带请求体。注释需说明每个查询参数是否必需、类型、默认值和含义。
- 使用
@OA\Get标签声明接口，path必须与路由一致（如/api/users） - 用
@OA\Parameter描述每个query参数，例如page、per_page、name -
@OA\Response中明确200返回的 JSON 结构（可用@OA\JsonContent引用模型或手动定义） - 补充常见错误响应，如
422（参数校验失败）或401（未认证）
二、POST 请求：聚焦请求体与数据验证
POST 通常用于创建资源，主体为 JSON 或表单数据。注释必须清晰描述请求体字段及其约束。
- 使用
@OA\Post，path指向创建端点（如/api/users） - 通过
@OA\RequestBody定义content，推荐使用@OA\JsonContent列出所有字段（required、type、example、description） - 若接受表单数据（
application/x-www-form-urlencoded），需另写@OA\MediaType并用@OA\Schema描述字段 - 响应部分除
201 Created外，应包含成功后返回的完整资源对象（含 ID、时间戳等）
三、PUT 请求：区分全量更新与语义准确性
PUT 表示“全量替换”，客户端需提交资源的完整状态。注释中要体现该语义，并确保字段覆盖完整。
-
@OA\Put的path应含资源标识，如/api/users/{id} - 用
@OA\Parameter标注path参数（id），注明required=true和type=integer -
@OA\RequestBody中的 JSON 内容应与对应资源模型字段严格对齐（包括不可为空字段），避免遗漏 - 建议在
@OA\Response中同时标注200 OK（更新成功）和404 Not Found（ID 不存在）
四、DELETE 请求：精简但不可省略关键信息
DELETE 逻辑看似简单，但注释仍需说明影响范围、前置条件和响应语义。
-
@OA\Delete的path同样需带{id}占位符（如/api/users/{id}） - 必须用
@OA\Parameter描述path参数，并说明其业务含义（如“用户唯一标识”） - 响应可为
204 No Content（推荐），也可返回200+ 简短确认消息（如{"message": "User deleted"}） - 务必标注可能的失败情形，如
403 Forbidden（权限不足）、404（资源已不存在）
实际编写时，建议将 OpenAPI 注释与控制器方法紧邻放置，配合 Laravel 的资源路由命名习惯（如 index、store、update、destroy），保持注释与代码意图高度一致。不复杂但容易忽略的是：每个参数的 in 属性（query/path/body）必须准确，否则生成的文档会误导前端调用。
