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 注释即可精准控制：

标签： php laravel html js json composer nginx app 工具 ai 路由 响应式布局 r