$ref“#/components/Response/”未找到@OA\Response(response=200)

Question

我正在尝试在Laravel项目中实现openAPI文档。我使用黑暗在线/L5-昂首阔步包，它构建在swagger-php之上以生成文档。我在推荐信方面面临一个问题。我希望将API调用的响应导出到控制器外部的一个外部文件，该文件是我正在记录的，为此，我使用了引用。但是，在这个特定的项目中，我在生成文档时遇到了这个恼人的错误：

跑步时：

php artisan l5-swagger:generate

我得到以下输出

  $ref "#/components/responses/" not found for @OA\Response(response=201) in \App\Http\Controllers\Organization\OrganizationController->get() in /data/www/nnaydenov/laravel-sandbox/app/Http/Controllers/Organization/OrganizationController.php on line 58

  at vendor/zircote/swagger-php/src/Loggers/DefaultLogger.php:31
     27▕         } else {
     28▕             $error_level = E_USER_WARNING;
     29▕         }
     30▕ 
  ➜  31▕         trigger_error($message, $error_level);
     32▕     }
     33▕ }
     34▕ 

      +33 vendor frames 
  34  artisan:37
      Illuminate\Foundation\Console\Kernel::handle()

这是我的控制器：

class OrganizationController extends Controller
{
    /**
     * @OA\Get(
     *     path="second-example",
     *     operationId="secondExample",
     *     @OA\Response(
     *         response=200,
     *         description="Hello from my awesome description",
     *         @OA\JsonContent(
     *             @OA\Property(
     *                 property="foo",
     *                 type="string",
     *                 example="bar",
     *             )
     *         )
     *     ),
     *     @OA\Response(
     *         ref="#/components/responses/foo",
     *         response=201
     *     )
     * )
     */
    public function get($id = null)
    {
        // ...
    }
}

这里是包含响应的文件，我想参考。它位于app/SomethingElse中：

<?php

/**
 * @OA\Response(
 *   response="foo",
 *   description="Sample description",
 *   @OA\JsonContent(
 *         @OA\Property(
 *             property="foo",
 *             type="string",
 *             example="bar",
 *         )
 *     )
 * )
 */

顶层注释，位于app\Http\Controller\Controller中：

namespace App\Http\Controllers;

use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="Api documentation",
 *      description="Api documentation",
 *      @OA\Contact(
 *          email="admin@admin.com"
 *      ),
 *      @OA\License(
 *          name="Apache 2.0",
 *          url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *      )
 * )
 *
 * @OA\Server(
 *      url=L5_SWAGGER_CONST_HOST,
 *      description="Demo API Server"
 * )
 *
 * @OA\Tag(
 *     name="Projects",
 *     description="API Endpoints of Projects"
 * )
 */
class Controller extends BaseController
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;

    // ...
}

我想这个项目有问题，我正在尝试实现它，因为相同的代码在普通的Laravel 8项目中工作。但是，我不知道如何调试这个问题。我尝试使用以下方法手动创建openapi.json文件

./vendor/bin/openapi . -o openapi.json

但是这会导致许多错误，我还没有解决。对于导致此错误的原因或如何调试此错误，有任何建议吗？

Answer 1

如果这是一个新项目，那么现在您可能正在使用swagger-php V4。在第4版中，分析器代码使用反射。这样做是为了能够使用注释或PHP 8属性。

缺点之一是不再检测到独立的文档块，因为没有任何反射来访问这些文档块。

解决这个问题的最简单方法是在注释之后添加一个class FooResponse{}行，swagger-php应该会再次找到它。

其他顶级注释(如@OA\Info或其他注释)也是如此。