Laravel中如何生成API接口文档_Laravel配合Swagger自动生成文档【教程】

Laravel需借助knuckleswtf/scribe实现自动化API文档生成，其通过解析控制器、验证规则和注释标签（如@bodyParam、@queryParam、@response）生成可交互文档，优于swagger-lume；配置时需注意中间件禁用、中文支持及注释规范。

Laravel中如何生成API接口文档_Laravel配合Swagger自动生成文档【教程】第1张

Laravel 本身不内置 API 文档生成功能，但通过 darkaonline/swagger-lume（轻量、Laravel 5.5+ 兼容）或更现代的 knuckleswtf/scribe，可以真正实现「写好接口逻辑 + 少量注释 → 自动生成可交互文档」。关键不是“能不能”，而是选对工具、避开注释冗余和路由扫描失效这两个坑。

用 scribe 替代 swagger-lume 更省心

swagger-lume 依赖手写 swagger.php 注释，且对 Laravel 10+ 的 PHP 8.1+ 属性语法支持弱；scribe 直接解析控制器方法、请求验证规则和返回示例，开箱即用。

安装：

composer require --dev knuckleswtf/scribe

发布配置：
```
php artisan scribe:install
```
生成文档：
```
php artisan scribe:generate
```
—— 默认输出到 public/docs，打开 public/docs/index.html 即可浏览
它会自动识别 request() 中的 FormRequest 类、@bodyParam 注释、@response 示例，不需要写完整 OpenAPI YAML

控制器里怎么写注释才被 scribe 正确提取

注释不是越多越好，scribe 只认特定标签，其他会被忽略。重点写清参数来源、必填性、示例值。

@bodyParam 用于 POST/PUT 请求体字段：

/**
 * 创建用户
 * @bodyParam name string required 用户姓名
 * @bodyParam email string required 邮箱，必须唯一
 * @bodyParam avatar file optional 头像文件
 */

@queryParam 用于 GET 查询参数：

/**
 * 获取用户列表
 * @queryParam page integer 是否分页，默认 1
 * @queryParam per_page integer 每页数量，默认 15
 */

返回响应建议用 @response 提供真实结构：

@response {
  "id": 1,
  "name": "张三",
  "email": "zhang@example.com"
}

避免写 @param 或 @return —— scribe 不读这些，纯属干扰

生成后接口测试失败？检查中间件和路由组

scribe:generate 是在 CLI 环境下运行的，不会加载 session、auth 或跨域中间件。如果接口加了 auth:sanctum 或 throttle，文档页里「Try it out」会 401 或 429。

临时禁用敏感中间件：在 config/scribe.php 的 middleware 数组中移除 auth、throttle 等项
确保 API 路由定义在 routes/api.php，且未被 Route::middleware('web') 包裹 —— web 中间件会触发 session 启动，导致 CLI 下报错
若用 Sanctum，需在 config/sanctum.php 中设置 'stateful' => []，或为文档域名（如 docs.test）加入白名单

如何让文档支持中文、自定义标题和排序

默认生成的文档是英文，且接口按路由注册顺序排列，不一定是业务逻辑顺序。

改语言：编辑 config/scribe.php，把 'language' => 'en' 改成 'zh'，并确保已发布本地化文件：
```
php artisan vendor:publish --tag=scribe-translations
```
改标题/描述：在 config/scribe.php 的 'title' 和 'description' 字段直接填写中文字符串
控制顺序：给每个控制器方法加 @group 用户管理、@subgroup 创建与更新，生成后自动分组折叠，比手动排序更可持续
去掉无意义的健康检查接口：在 config/scribe.php 的 'include' => [] 中明确列出要包含的控制器，别用 scan 模式扫全项目