scribe更适合日常迭代，能自动扫描路由、解析验证规则与响应结构，支持html/openapi/postman导出；l5-swagger则适合openapi生态对接，需严格遵循@oa注释规范。
用 Scribe 或 L5-Swagger 生成 Laravel API 文档，核心是“写得规范、配得准确、跑得自动”。不靠手写 Markdown，也不靠 Postman 快照，而是让文档随代码一起生长。
选对工具：Scribe 更适合日常迭代
Scribe（knuckleswtf/scribe）是当前 Laravel 社区最活跃、适配性最强的文档工具。它能自动扫描路由、读取 FormRequest 验证规则、解析 Resource 响应结构，还能导出 HTML、OpenAPI 3.0、Postman 集合。
- 安装简单：
composer require --dev knuckleswtf/scribe - 初始化快：
php artisan scribe:install（自动发布配置+创建默认视图） - 支持 Laravel 9/10/11，对 API 资源路由、中间件分组、Route Model Binding 兼容良好
- 不依赖 OpenAPI 注解语法，用更贴近 PHP 开发者习惯的
@bodyParam、@response等注释即可控制输出
写好注释：关键字段不能漏
注释不是装饰，是文档的数据源。控制器方法上方的 PHPDoc 必须覆盖三类信息：
-
接口归属：用
@group 用户管理或@subgroup 创建与更新归类，便于前端按模块查阅 -
参数定义：
@queryParam page int 可选。页码，默认为1@bodyParam email string required 邮箱地址，需唯一-
@urlParam id integer required 用户ID（对应/users/{id}中的路径变量）
-
响应示例：
@response 200 {"data": {"id": 1, "name": "Tom"}}-
@responseField data.id integer 用户唯一标识（用于字段级说明） -
@authenticated标记需登录接口，Scribe 会自动加入 Token 输入框
配准环境：让文档真正可用
生成的文档要能访问、能测试、能同步，配置必须到位：
- 在
config/scribe.php中设置'base_url' => env('APP_URL') . '/api'，确保请求示例中的域名和前缀正确 - 启用
'routes' => ['prefix' => 'api']，只扫描routes/api.php下的路由，避免混入 Web 路由 - 若使用 Sanctum 或 Passport，配置
'auth' => ['type' => 'bearer', 'in' => 'header']，文档页面将自动添加 Authorization 输入框 - 开启
'try_it_out' => true，允许在文档页直接点击 “Send Request” 测试接口
接入流程：CI/CD 中自动更新文档
文档失效往往源于“忘了更新”，解决办法是把它变成构建环节的一部分：
- 在 GitHub Actions / GitLab CI 的部署流程中，添加步骤：
php artisan scribe:generate --force - 生成目标设为
public/docs，配合 Nginx/Apache 直接托管，无需额外服务 - 搭配
--watch模式用于本地开发预览：php artisan scribe:generate --watch - 导出 OpenAPI 文件（
public/docs/openapi.yaml）可同步推送到 Stoplight、Redoc 或内部 API 管理平台
备选方案：L5-Swagger 适合 OpenAPI 生态对接
当项目需对接外部系统、已有 OpenAPI 工具链或强制要求符合 Swagger UI 规范时，darkaonline/l5-swagger 是更稳妥的选择：
- 必须严格匹配版本：Laravel 11 对应
l5-swagger:^8.4+；Laravel 10 对应^9.0 - 注释必须以
@OA\开头（非旧版@SWG\），且@OA\Get的path必须与routes/api.php完全一致（包括前缀、变量名大小写） - 生成命令：
php artisan l5-swagger:generate，文档 JSON 默认输出到storage/api-docs - 访问地址为
/api/documentation（需确认config/l5-swagger.php中swagger_ui_enabled为 true）
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
