LaravelAPI如何做文档_Laravel生成API文档工具使用【教程】-Laravel-PHP中文网

scribe是生成laravel api文档最稳方案，因apiato和laravel-apidoc-generator已过时：后者依赖不支持openapi 3.0+的swagger-php v2，无法解析php 8.1+类型注解（如string|null），且路由嵌套、中间件参数提取常出错。

laravelapi如何做文档_laravel生成api文档工具使用【教程】

用 scribe 生成 Laravel API 文档最稳，apiato 或 laravel-apidoc-generator 已基本掉队。

为什么别碰 `laravel-apidoc-generator`

它依赖过时的 zircote/swagger-php v2，不支持 OpenAPI 3.0+；Laravel 9+ 的 PHP 8.1+ 类型注解（如 string|null、array<int string></int>）会直接解析失败，报错 Unable to parse type "string|null"。更麻烦的是路由组嵌套、中间件参数提取经常漏掉，文档和实际接口对不上。

实操建议：

ApiPost接口调试与文档生成工具

ApiPost是一个支持团队协作，支持模拟POST、GET、PUT等常见请求，并可直接生成文档的API调试、管理工具，ApiPost是后台接口开发者或前端、接口测试人员的工作必备工具。快速生成、一键导出API文档。感兴趣的朋友快来下载吧。软件说明ApiPost官方版是一款十分出色的接口调试与文档生成工具，ApiPost官方版界面美观大方，功能强劲实用，支持团队协作，支持模拟POST、GET、PUT等常见请求，是后台接口开发者或前端、接口测试人员的工作必备工具。软件特色更方便支持接口调试的同时快速生成、一键

下载

新项目绝对绕开，老项目升级前先评估是否值得花时间修 patch
若必须用，得手动在每个 @bodyParam 注释里写死类型，比如 @bodyParam user_id integer required 用户ID，不能依赖自动推导
配合 php artisan api:generate --routes="api.php" 时，务必确认 config/apidoc.php 中 'routeMatcher' => 'exact'，否则带参数的路由（如 /users/{id}）会被跳过

`scribe` 怎么快速跑起来

它原生支持 Laravel 8+、PHP 8.0+，自动读取路由、控制器方法、验证规则、Eloquent 模型注释，还能生成 Postman 集合和 Markdown。

实操建议：

装包：composer require knuckleswtf/scribe，然后 php artisan scribe:install
关键配置在 config/scribe.php：把 'type' => 'static' 改成 'type' => 'laravel'，否则无法识别 Route::middleware('auth:sanctum') 这类中间件标记
生成命令是 php artisan scribe:generate，不是 api:generate；加 --force 才会覆盖已有文件，否则默认跳过
想让响应示例带真实数据？给控制器方法加 @responseFile responses/user.json，文件放 resources/docs/responses/ 下，内容必须是合法 JSON，否则构建中断

怎么让文档准确反映权限和错误格式

很多团队只写成功响应，结果前端调用时 401/422 返回结构和文档完全两样，联调卡半天。

实操建议：

在控制器方法上加 @responseField status integer 401 + @responseField message string "Unauthenticated."，scribe 会合并进 “Errors” 区块
验证失败统一走 ValidateRequest 基类？在基类方法里补 @response 422 {"message":"The given data was invalid.","errors":{"email":["The email field is required."]}}
中间件抛的异常（比如自定义 EnsureApiToken）需在 app/Exceptions/Handler.php 的 render() 里显式标记为 API 响应，否则 scribe 不识别

部署后文档打不开或样式错乱

静态 HTML 文档默认输出到 public/docs，但 Nginx/Apache 若没配好，访问 /docs 会 404 或加载空白页——这不是代码问题，是 Web 服务器没把请求代理给 Laravel 的 public 目录。

实操建议：

Nginx 下确认 location /docs { alias /path/to/your/project/public/docs; }，注意 alias 末尾不能带斜杠，且路径必须绝对
Apache 要启用 mod_rewrite，并在 .htaccess 同级目录加 Options +FollowSymLinks，否则 JS/CSS 路径 404
如果用了 Cloudflare 或 CDN，确保没缓存 /docs/* 路径，否则改完文档刷新不出来

真正难的不是生成，是让每个 @bodyParam 和实际 request()->validate() 规则严格对齐；少写一个 required，前端就得多试三次才知道字段到底要不要传。