用 @OA\Get 这类注解前，先装好 darkaonline/l5-swagger
不装这个包，写再多 @OA\Get、@OA\Parameter 注解都没用——Laravel 不会识别，php artisan l5-swagger:generate 会直接报错说找不到类。它不是 Laravel 自带的，也不是 PHP-FIG 标准，纯靠这个包把注解翻译成 OpenAPI JSON。
安装时注意 Laravel 版本匹配：darkaonline/l5-swagger:^8.0 对应 Laravel 9/10；Laravel 11 要用 ^8.4 以上（否则 config/l5-swagger.php 里 routes.api 配置项会失效）。
运行 composer require "darkaonline/l5-swagger:^8.4" 后，务必执行 php artisan vendor:publish –provider="L5Swagger\L5SwaggerServiceProvider"发布后检查 config/l5-swagger.php 中的 paths.annotations，默认是 app/Http/Controllers，如果你的 API 控制器在 app/Http/Controllers/Api/V1，得手动加进去，不然扫描不到别在 routes/web.php 里写 API 注解——路由没注册到 API 中间件组，Swagger UI 点“Try it out”会 401 或 404
@OA\Get 和 @OA\Post 必须和路由定义对齐
注解不是装饰品，它得和 routes/api.php 里的实际路由完全一致：HTTP 方法、URL 路径、参数占位符名称，一个字符都不能差。比如路由写的是 Route::get(‘/users/{id}’, [UserController::class, ‘show’])，那注解里的 path="/users/{id}" 就不能写成 /users/{user_id}，否则 Swagger UI 里生成的请求 URL 是错的，调试时永远 404。
路径参数名必须一致：{id} 就是 {id}，别改成 {userId}，哪怕变量名在方法里叫 $userId查询参数（?page=1&sort=name）要用 @OA\Parameter(name="page", in="query", …) 显式声明，不写就不会出现在文档的“Parameters”面板里如果路由用了前缀如 Route::prefix(‘api/v1’)->group(…)，注解里的 path 就只写 /users，不要重复写 /api/v1/users，否则生成的路径会变成双份前缀
@OA\Schema 定义响应体时，别直接引用 Eloquent 模型类
@OA\Schema(ref="#/components/schemas/User") 看起来省事，但一旦模型字段动态变化（比如加了 appends、改了 $casts、用了 makeHidden），文档就和真实返回不一致。Swagger 不会运行 PHP 代码去反射模型，它只认你手写的 @OA\Property。
更麻烦的是：Eloquent 的 $dates、$casts、访问器（accessor）不会自动转成 OpenAPI 类型。比如 is_active 是 tinyint(1)，PHP 返回布尔值，但没声明 type="boolean"，Swagger 就当它是整数，前端 Typescript 生成器会产出错误类型。
响应体老实用 @OA\Schema + @OA\Property 手动列字段，尤其注意 type 和 format（date-time 不能写成 datetime）数组字段写 @OA\Property(type="array", @OA\Items(type="string"))，别漏掉 @OA\Items，否则 Swagger UI 显示 “unknown type”如果返回的是资源集合（UserResource::collection()），注解里要写 @OA\Response(… @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/User")))，不是直接 ref 到单个 schema
生成文档后打不开 UI？检查 SWAGGER_UI_ENABLED 和中间件
运行 php artisan l5-swagger:generate 成功，不代表能访问 /api/documentation。默认配置下，这个路由只在 APP_ENV=local 时启用，生产环境直接 404。另外，Laravel 10+ 默认加了 PreventRequestsDuringMaintenance 中间件，如果站点进了维护模式，Swagger UI 也进不去，但错误提示是 503，容易误判为配置问题。
临时开启：在 .env 加 SWAGGER_UI_ENABLED=true，并确保 APP_ENV=local 或在 config/l5-swagger.php 里把 swagger_ui_enabled 设为 true访问路径是 /api/documentation（不是 /docs 或 /swagger），且必须走 HTTPS（如果 APP_URL 配了 https）如果用了 Sanctum 或 Passport，Swagger UI 的 “Authorize” 按钮点开后填的是 Bearer Token，但实际请求头要加 Authorization: Bearer xxx，少个空格或大小写错误都会 401
最常被忽略的是：注解写在控制器方法里，但那个方法根本没被路由指向——生成的 JSON 里压根没有这条接口，UI 上自然看不到。别只盯着注解语法，先 php artisan route:list | grep users 确认路由存在。
评论(0)