$ref "#/components/responses/" 未找到 @OA\Response（响应=200）

Question

我正在尝试在 Laravel 项目中实现 openAPI 文档。我正在使用 darkaonline/l5-swagger package, which is built on top of 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/Something/SomethingElse:

<?php

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

顶级注释，位于app\Http\Controllers\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 个属性。

一个缺点是不再检测到 stand-alone 文档块，因为没有反射来访问它们。

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

这同样适用于其他顶级注释，如 @OA\Info 或其他。

$ref "#/components/responses/" 未找到 @OA\Response（响应=200）

$ref "#/components/responses/" not found for @OA\Response(response=200)

laravel

openapi

swagger-php