使用L5-Swagger生成API文档时遇@OA\PathItem()未找到错误

问题描述 #

我在Laravel项目中采用分文件方式编写API的Swagger文档，已创建app/swagger/SwaggerCambio.php文件，包含@OA\Info和@OA\Get注解，且在l5-swagger.php中配置注解目录为base_path('app/swagger')，但生成文档时触发上述错误。

解决方案 #

核心原因 #

OpenAPI注解规范要求：@OA\Get这类HTTP方法注解必须嵌套在@OA\PathItem注解内部，否则swagger-php无法识别有效的路径项；同时需确保命名空间与目录结构符合Laravel的PSR-4自动加载规则，避免注解扫描失败。

修复步骤 #

1. 修正注解结构与命名空间
   修改SwaggerCambio.php代码，将@OA\Get包裹在@OA\PathItem中，并添加空类承载注解（部分swagger-php版本要求注解关联到类）：

<?php

namespace App\Swagger; // 修正命名空间首字母大写，匹配PSR-4规范

use OpenApi\Annotations as OA;

/**
 * @OA\Info(
 *     title="API de Câmbio",
 *     version="1.0.0",
 *     description="API para obter a cotação do dólar em relação ao real."
 * )
 */

/**
 * @OA\PathItem(path="/api/auth/cotacao-dolar")
 */
class SwaggerCambio
{
    /**
     * @OA\Get(
     *     tags={"Cotação do Dólar"},
     *     summary="Obter cotação do dólar",
     *     description="Obtém a cotação atual do dólar em relação ao real.",
     *     @OA\Response(
     *         response=200,
     *         description="Cotação do dólar obtida com sucesso",
     *         @OA\JsonContent(
     *             @OA\Property(property="cotacao_dolar_venda", type="string", description="Cotação de venda do dólar"),
     *             @OA\Property(property="valor_em_dolar", type="string", description="Valor em dólar correspondente ao valor em reais fornecido")
     *         )
     *     ),
     *     @OA\Response(
     *         response=500,
     *         description="Erro ao obter a cotação do dólar"
     *     )
     * )
     */
    public function getCotacao() {} // 空方法，仅用于承载注解
}

2. 同步目录配置
   确保l5-swagger.php中的注解目录与命名空间对应（建议目录首字母大写）：

'annotations' => [
    base_path('app/Swagger'),
],

3. 重新生成文档
   执行命令重新生成：

php artisan l5-swagger:generate

内容的提问来源于stack exchange，提问作者Pietro SA