Swagger 是个很好的api文档生成方案，但是需要手动给api写大量的注解，很麻烦，很多开发者在使用 Swagger 注解时会有的感受：虽然功能强大，但注解本身还是会增加代码的“噪音”，并且存在一定的学习曲线。
除了手写注解，其实存在更简单、自动化程度更高的办法。这个方法的核心思想是通过自动分析你的代码来生成文档，而不是依赖手写注释。
他会自动扫描你的路由、控制器方法、FormRequest 和 API Resource，然后根据这些信息生成一个基础的 OpenAPI 文档。你只需要在少量复杂或模糊的地方补充注解即可。
推荐工具：knuckleswtf/scribe
Scribe 是目前 Laravel 生态中最受欢迎的自动化 API 文-档生成工具，它就是为此而生的。
Scribe 的工作流程：
- 安装和配置：
composer require --dev knuckleswtf/scribe 然后 php artisan vendor:publish --tag=scribe-config。
- 运行生成命令：
php artisan scribe:generate。
- Scribe 会做什么？
- 分析路由：读取
routes/api.php，知道有哪些端点、URL、请求方法和应用的中间件。
- 分析控制器方法：找到对应的控制器方法。
- 分析 FormRequest：如果你的方法注入了
UserUpdateRequest，Scribe 会自动读取 rules() 方法，并将 name, phone 等参数标记为请求体参数，连同验证规则（如 required, max:50）一起展示在文档里。这是它比纯 Swagger 注解强大的地方！
- 分析 API Resource：如果你在控制器中返回了
new UserResource($user)，Scribe 会尝试分析 UserResource 的 toArray() 方法，推断出返回的 JSON 结构。
- 模拟请求获取响应：Scribe 甚至可以配置为“真实地”向你的 API 发送一次请求（在测试环境中），然后记录下真实的响应，作为文档示例。
与纯手写注解相比，Scribe 的优势：
- 自动化程度极高：80% 的信息（URL、方法、参数、验证规则）都是自动生成的，你基本不用写注解。
- “开箱即用”：只需运行一条命令，就能得到一份相当不错的文档。
- 与注解兼容：对于 Scribe 无法自动推断的复杂逻辑（比如一个复杂的
if/else 返回不同结构），你仍然可以使用 @bodyParam 等 Scribe 提供的注解来补充说明，无缝结合。
- 输出多种格式：可以生成漂亮的 HTML 页面，也可以生成 Postman Collection 和 OpenAPI (Swagger) JSON 文件。
如何使用 Scribe 导出到 Postman？
- 运行
php artisan scribe:generate。
- 在生成的文档页面 (
http://你的域名/docs) 的右上角，通常会有一个 “View Postman collection” 或类似的链接。
- 点击该链接，你会得到一个 JSON 文件，直接导入 Postman 即可。
结论：对于追求“更简单办法”的你来说，Scribe 几乎是完美的答案。它在自动化和灵活性之间取得了绝佳的平衡。
—
对于你已经写好了 API 代码的现状，我强烈推荐你首先尝试 knuckleswtf/scribe。
它几乎是为你量身定做的解决方案，可以最大程度地利用你已有的规范代码（FormRequest, API Resource），以最小的代价，快速生成一份高质量、可直接导入 Postman 的 API 文档。
提供