Swagger PHP中Resolver error 'Could not resolve reference: undefined'问题求助

问题根源 #

你遇到的Could not resolve reference: undefined错误，核心原因有两个：

1. Schema引用格式错误：接口注解里用了文件路径app/Http/Resource/CompetitionTeamResource作为ref值，但Swagger PHP识别的是Schema定义中schema属性指定的名称，而非文件路径。
2. 引用目标不匹配：Schema定义里schema="CompetitionTeamController"，但接口里引用的是完全不相关的路径，两者根本对应不上。

修复步骤 #

1. 修正接口中的Schema引用格式和目标

把接口里的ref值改成Swagger标准的Schema引用路径，指向你定义的CompetitionTeamController Schema：

/**
 *  Update
 *
 * @OA\Put(
 *     path="competitions/{uuid}/teams/{team_id}",
 *     summary="Updating resource in storage.",
 *     description="Updating resource in storage with new information.",
 *     operationId="updateTeam",
 *     tags={"compTeamController"},
 *     security={{"bearer": {}}},
 *     @OA\Response(
 *         response=200,
 *         description="Success",
 *         @OA\JsonContent(
 *             @OA\Property(
 *                 property="data",
 *                 ref="#/components/schemas/CompetitionTeamController"
 *             ),
 *         )
 *     ),
 *     @OA\Response(
 *         response=403,
 *         description="Access denied to team.",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Access denied to team.")
 *         )
 *     ) 
 * )
 */

2. 确保Schema定义能被Swagger PHP扫描到

你的Schema注解需要放在Swagger扫描范围内的文件中（比如对应的模型类、Resource类，或者专门的Schema定义文件），如果是Laravel项目，默认扫描app/目录下的文件，只要注解所在文件在这个目录里就没问题。

3. 修正403响应的Type错误（额外优化）

你403响应里的type="Access denied to team."是错误的，Type应该是数据类型（比如string），提示文本要放在example属性里，上面的代码已经帮你修正了这一点。

验证修复 #

重新生成Swagger文档，若没有其他拼写错误，Resolver错误应该会消失，接口的200响应会正确关联你定义的Schema。

内容的提问来源于stack exchange，提问作者Carina George