推荐使用 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 原生风格，文档跟代码一起迭代，不复杂但容易忽略。
