Laravel官方推荐的laravel/api-documentation包5分钟即可搭建多模态API文档，支持Swagger UI、ReDoc和OpenAPI JSON三合一输出，自动解析路由与控制器，通过PHP属性标注接口，适配多环境与版本管理。

直接用 Laravel 官方推荐的 laravel/api-documentation 扩展包，5 分钟就能跑起多模态 API 文档，支持 Swagger UI、ReDoc 和 OpenAPI JSON 三合一输出，无需手写注释也能自动解析路由和控制器。

安装与初始化

在 Laravel 13 或 Laravel 12 项目中执行以下命令：

• 安装扩展包：composer require laravel/api-documentation
• 生成默认配置与前端资源：php artisan make:api-docs --install
• 注册文档路由后，/docs 路径即可访问交互式界面

启用双模式文档输出

默认只启用 Swagger UI，如需同时支持 ReDoc 静态视图和机器可读 JSON，修改配置：

Laravel Cloud

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

下载

• 运行命令切换为混合模式：php artisan config:setapi-docs.mode=hybrid
• 配置生效后，自动开放三个路径：
  /docs（Swagger UI）
  /docs/redoc（ReDoc 页面）
  /docs/api.json（OpenAPI 3.1 标准 JSON）

用 PHP 属性快速标注接口

避免冗长 DocBlock，直接在控制器方法上使用 OpenAPI 属性声明关键信息：

• #[OpenApi\Operation(id: "getUsers", description: "获取用户列表")]
• #[OpenApi\Path(path: "/api/users")]
• 请求体、响应结构、认证方式等都可通过 #[OpenApi\RequestBody]、#[OpenApi\Response] 等属性定义
• 文档生成器会自动扫描这些属性，无需额外运行生成命令——保存即更新

适配多环境与版本管理

开发、测试、生产环境可独立维护文档内容：

• 配置文件 config/api-docs.php 支持 environments 键，按环境启用不同路由组或过滤条件
• API 版本控制天然兼容：若路由定义为 Route::prefix('api/v2')，文档会自动识别并归类到 v2 分组
• 支持通过中间件控制文档可见性，例如仅允许 local 或 staging 环境访问 /docs