用 Laravel 写靠谱 API 文档只需三步：选 Scribe 等工具、在控制器用标准注释声明参数与响应、运行命令生成可交互页面；半天即可上线，支持自动更新和团队协作。
想用 Laravel 写出靠谱、能上线、团队看得懂的 API 文档，不需要先成为专家。核心就三点：选对工具、写对注释、跑对命令。只要按步骤来，半天就能产出可交互、带测试功能的正式文档页面。
选一个趁手的文档生成器
目前 Laravel 生态里最稳、社区支持最全的是三个工具，按推荐顺序选：
- Scribe：新手友好度最高，注释语法简洁，自动生成请求示例和响应示例，支持导出静态 HTML，CI/CD 集成方便；适合大多数中小型项目和快速迭代场景
- L5-Swagger：基于 OpenAPI 标准，生成 Swagger UI 和 ReDoc 页面，对接外部系统（如 Postman、Apifox）兼容性好；但注解写法稍重，路径和参数名必须与路由严格一致，容易因小错导致 404
- Laravel 12 原生多模态文档（laravel/pennant + OpenApi Attributes）：Laravel 12 新增特性，用 PHP 属性（#[OpenApi\Operation]）代替注释，类型安全、IDE 支持好、不易拼错；但仅限 Laravel 12+，不兼容旧版本
如果你刚上手，直接装 Scribe；如果项目已用 Sanctum 或 Passport 认证，Scribe 对 Bearer Token 的文档说明也更直观。
在控制器里写清楚“它要什么、给什么”
文档不是写给人看的说明书，而是让机器能解析出结构的“元数据”。重点不是文采，是字段名、位置、是否必填、示例值这四样。
以 Scribe 为例，在控制器方法上方加 DocBlock：
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
/**
* 获取用户列表
*
* @queryParam page int 可选。页码，默认为 1。Example: 2
* @queryParam search string 可选。用户名模糊搜索关键词。Example: "zhang"
* @response 200 {
* "data": [{"id": 1, "name": "张三", "email": "zhang@example.com"}],
* "meta": {"current_page": 2}
* }
*/关键点：
- 路径参数（如
{id}）、查询参数（?page=1）、请求体字段（POST /users的 JSON 字段）都要单独声明，不能只靠注释文字描述 -
@response里的 JSON 示例必须是真实格式，缩进不重要，但键名、嵌套层级、数据类型要和实际返回一致 - 不要写“返回用户信息”，要写“返回 User 资源数组，含 id、name、email 字段”
配置好路径、生成并验证文档
装完工具后别跳过配置环节，否则扫描不到你的控制器：
- Scribe：运行
php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config，然后检查config/scribe.php中的routes是否包含你 API 的路由组（比如api中间件组） - L5-Swagger：发布配置后，重点改
config/l5-swagger.php的paths.annotations，确保包含app/Http/Controllers/Api这类实际存放控制器的目录 - 生成命令统一是：
php artisan scribe:generate或php artisan l5-swagger:generate
生成成功后，打开 public/docs（Scribe）或 /api/documentation（L5-Swagger），点“Try it out”实测接口。如果报 401，检查是否配置了认证头；如果报 404，回头核对注解 path 和 routes/api.php 是否完全一致（连斜杠数量都不能差）。
让文档真正活起来
写完一次不算完，要让它持续有用：
- 把生成命令加入 Git Hook 或 CI/CD 流程，每次合并到 main 分支时自动更新文档
- 在 PR 模板里加一条：“API 修改需同步更新对应注释”，把文档维护变成代码审查的一部分
- 给前端同事分享
/docs链接，而不是发 Word 或 Markdown —— 他们可以直接填参、点发送、看响应，比读文字快十倍
不复杂但容易忽略。
