Laravel文档完善新手指南：从零基础到独立完成企业级API文档编写【教程】-php教程-PHP中文网

用 Laravel 写靠谱 API 文档只需三步：选 Scribe 等工具、在控制器用标准注释声明参数与响应、运行命令生成可交互页面；半天即可上线，支持自动更新和团队协作。

laravel文档完善新手指南：从零基础到独立完成企业级api文档编写【教程】

想用 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：

/**
 * 获取用户列表
 * 
 * @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}
 * }
 */

关键点：

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

路径参数（如 {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 是否完全一致（连斜杠数量都不能差）。