Swagger-PHP @OA\Items() is required when @OA\Schema() has type "array"の解決法

はじめに

Laravel + Swagger/OpenAPI でAPIを開発する際に書くアノテーション（@OA\から始まるコメントみたいなの）に問題があり、Swaggerのドキュメントを出力する際にエラーが発生した。。。

$ php artisan l5-swagger:generate

Regenerating docs default

   ErrorException 

  @OA\Items() is required when @OA\Schema() has type "array" in \App\Http\Controllers\Mobile\Version1\SearchController->getJobs() in /var/www/html/app/Http/Controllers/Mobile/Version1/SearchController.php on line 247

  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▕ 

      +35 vendor frames 
  36  artisan:37
      Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))

GETメソッドでarrayのパラメーターを渡そうとしたのだが、その部分のアノテーションが原因であろうと推測。。

@OA\Schemaの中に@OA\Itemsを入れると解決

👇はエラーが出るパターン

    /**
     * @OA\Get(
     *     path="/mobile/v1/job/jobs",
     *     operationId="job-get-jobs",
     *     tags={"job"},
     *     summary="jobの一覧",
     *     description="jobの一覧を取得します",
     *     @OA\Parameter(
     *         name="category_id",
     *         in="query",
     *         example="[1, 2, 3]",
     *         description="カテゴリのIDの配列を指定してください。",
     *         required=true,
     *         @OA\Schema(type="array"),
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="成功",
     *         @OA\JsonContent(ref="#/components/schemas/MobileApiItemsResponse")
     *     )
     * )
     */
    public function getJobs(ApiTokenRequest $request)
    {
      // コントローラーの処理
    }

👇がOKなパターン

    /**
     * @OA\Get(
     *     path="/mobile/v1/job/jobs",
     *     operationId="job-get-jobs",
     *     tags={"job"},
     *     summary="jobの一覧",
     *     description="jobの一覧を取得します",
     *     @OA\Parameter(
     *         name="category_id",
     *         in="query",
     *         example="[1, 2, 3]",
     *         description="カテゴリのIDの配列を指定してください。",
     *         required=true,
     *         @OA\Schema(
     *             type="array",
     *             @OA\Items(type="integer"),
     *         ),
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="成功",
     *         @OA\JsonContent(ref="#/components/schemas/MobileApiItemsResponse")
     *     )
     * )
     */
    public function getJobs(ApiTokenRequest $request)
    {
      // コントローラーの処理
    }

@OA\Items(type="integer"),のように、arrayの中身も型を指定しないといけないようです

普通に処理は通るので、Swaggerのドキュメントを出力する際にエラーが発生すると困りますね〜・・・