Laravel文档完善神器Scribe：一键生成可交互的RESTful API文档【介绍】-php教程-PHP中文网

scribe为laravel生成可交互api文档的核心是装得对、注得准、跑得通；它从路由、控制器注释和验证逻辑自动提取信息，生成html页面、openapi文件和postman集合。

laravel文档完善神器scribe：一键生成可交互的restful api文档【介绍】

用 Scribe 为 Laravel 项目生成可交互的 RESTful API 文档，核心就三点：装得对、注得准、跑得通。它不依赖抓包或手动维护，而是从你已有的路由、控制器注释和验证逻辑里“读懂”接口，自动生成带测试功能的 HTML 页面、OpenAPI 文件和 Postman 集合。

安装与初始化要一步到位

在 Laravel 项目根目录执行：

composer require --dev knuckleswtf/scribe（推荐加 --dev，文档工具本就不该进生产）
php artisan scribe:install（新版命令，比 vendor:publish 更简洁，自动创建 config/scribe.php）
检查 config/scribe.php 中的 'routes' 配置，默认可能只扫 web 组——务必显式加上 'prefixes' => ['api/*']，否则 API 路由全被跳过

注释不是可有可无，而是文档骨架

Scribe 只识别特定 PHPDoc 标签，其他注释一概忽略。关键标签必须写在控制器方法上方：

Laravel 13.2.0

PHP中文网提供Laravel 13.2.0版本下载，Laravel框架是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。

下载

@group 用户管理：把接口归入分组，生成时自动分类
@queryParam page integer optional 默认1：GET 参数，类型、是否必填、默认值、说明缺一不可
@bodyParam email string required 邮箱地址：POST/PUT 请求体字段，required 或 optional 必须声明
@response {"id":1,"name":"张三"}：提供真实结构的 JSON 示例，Scribe 会格式化并展示在文档中
避免 @param、@return 等通用标签——Scribe 不读它们，纯属干扰

生成与预览不能只靠双击 index.html

生成命令是 php artisan scribe:generate，但输出路径 public/docs 是静态资源目录：

直接双击 index.html 会因跨域加载 JS 失败而白屏——这是最常见卡点
正确预览方式：php -S localhost:8000 -t public/docs，然后访问 https://www.php.cn/link/fcbb3a1c04ec11f1506563c26ca63774
如需部署到 Nginx/Apache，确保服务器允许 index.html 作为入口，且未启用重写规则拦截 /docs/ 下的静态资源
加 --force 参数可绕过缓存，比如 php artisan scribe:generate --force，适合调试阶段

认证与分组配置决定文档可用性

若 API 需要 Sanctum 或 Passport 认证，光写 @authenticated 不够：

在 config/scribe.php 的 'auth' => ['sanctum'] 中，值必须与中间件注册名完全一致（如 auth:sanctum 对应中间件名 'sanctum'，不能写成 'auth:sanctum'）
使用 Route::apiResource() 时，Scribe 不识别隐式行为，需在路由定义前补注释块：
/** @group 文章管理 */
放在 Route::apiResource('posts', ...) 上方
想按模块拆分文档？在 'routes' 配置里用多个数组项分别指定不同前缀和分组名，Scribe 会自动聚合