Laravel如何生成API文档？（Swagger/OpenAPI教程）

推荐使用 knuckleswtf/scribe 生成 Laravel API 文档，它自动扫描路由、解析验证规则与响应结构，支持 HTML、OpenAPI 3.0、Postman 导出；需规范路由定义、使用 FormRequest 和 JSON 响应，并通过 PHPDoc 注释定制文档内容。

用 Laravel 生成 API 文档，最主流、维护好、集成顺的方式是通过 Swagger / OpenAPI 标准，配合 darkaonline/laravel-swagger 或更现代的 knuckleswtf/scribe（推荐）。下面讲清核心思路和实操步骤，不绕弯。

选对工具：Scribe 比传统 Swagger 包更省心

旧方案（如 laravel-swagger）依赖手动写注释 + 静态 JSON 生成，更新易断、不支持 Laravel 9+ 新特性；knuckleswtf/scribe 是当前 Laravel 社区首选——它能自动扫描路由、提取验证规则、解析响应结构，还能导出 HTML、OpenAPI 3.0 JSON/YAML、甚至 Postman 集合。

• 安装：composer require --dev knuckleswtf/scribe
• 发布配置：php artisan scribe:install
• 生成文档：php artisan scribe:generate

让接口自动被识别：规范写法是关键

Scribe 不是“魔法”，它靠分析控制器方法、请求类、返回响应来推导文档。你需要保持基本约定：

• 路由定义在 routes/api.php，用标准资源/命名路由，避免闭包路由
• 控制器方法要有明确的 HTTP 方法注释（@GET, @POST），或直接用 Laravel 8+ 的 Route Model Binding + 类型提示
• 请求校验统一走 FormRequest 类，Scribe 会自动读取 rules() 和 messages()
• 响应尽量用 response()->json() 或 Resource 类，配合 @response 注释可补全示例

定制文档内容：加注释比改代码更高效

默认生成可能缺描述、参数说明或示例响应。在控制器方法上方加 PHPDoc 注释即可精准控制：

• @group Users —— 归类到「Users」分组
• @bodyParam email string required Email address —— 定义请求体字段
• @response {"id":1,"name":"Tom"} —— 写死一个响应示例
• @responseField id integer ID of the user —— 说明响应字段含义

所有可用注释见 Scribe 官方注释参考，无需背，按需查。

部署与访问：生成静态 HTML 最实用

php artisan scribe:generate 默认输出到 public/docs，生成纯 HTML 页面，开箱即用：

• 本地查看：http://your-app.test/docs
• CI/CD 中加入该命令，每次发布自动更新文档
• 支持搜索、深色模式、响应式布局，手机也能看
• 同时产出 public/docs/openapi.yaml，可导入 Swagger UI、Redoc 或第三方平台（如 Stoplight）

基本上就这些。不用搭服务、不碰 YAML 手写、不配 Nginx 重写——Laravel 原生风格，文档跟代码一起迭代，不复杂但容易忽略。