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

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

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。

Krea AI

多功能的一站式AI图像生成和编辑平台

下载

• 临时禁用敏感中间件：在 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 模式扫全项目

实际项目里最常卡住的，是以为「写了注释就等于文档可用」，结果发现 @bodyParam 拼错成 @body_param，或漏了 required 导致字段被忽略。生成前先跑一次

php artisan scribe:generate --dry-run