使用light/yii2-swagger在PHP8.2报错：Required @OA\PathItem() not found

原因分析 #

升级到PHP8.2后，light/yii2-swagger依赖的核心库zircote/swagger-php对注解解析规则变得更严格，旧版本中直接在方法上标注@OA\Get的写法不再兼容，必须显式通过@OA\PathItem来关联路径与HTTP方法。

解决方案 #

1. 更新兼容PHP8的依赖包 #

先确保使用的light/yii2-swagger和zircote/swagger-php版本支持PHP8.x：

• 执行Composer命令更新依赖：

  composer require light/yii2-swagger:^1.4 zircote/swagger-php:^4.0
  

  （版本号可根据实际兼容情况调整，优先选择最新稳定版）

2. 调整Swagger注解写法 #

修改方法上的注解，将@OA\Get包裹在@OA\PathItem中，符合新版swagger-php的解析要求：

/**
 * @OA\PathItem(
 *     path="/api/index",
 *     @OA\Get(
 *         @OA\Response(response="200", description="Get default action")
 *     )
 * )
 * @return array
 */
public function actionIndex()

3. 验证控制器类注解完整性 #

确保ApiController类上的基础注解格式正确，可补充服务器地址注解提升文档完整性：

/**
 * @package app\controllers\api
 *
 * @OA\Info(title="Project API", version="1.0")
 * @OA\Server(url="http://your-project-domain.com")
 */
class ApiController extends Controller

4. 清理缓存并验证结果 #

执行Yii缓存清理命令，确保注解解析缓存被更新：

./yii cache/flush-all

重新访问Swagger文档页面，确认错误是否消失。

内容的提问来源于stack exchange，提问作者Alex Victorov