如何在php中为swagger定义和使用可重用的参数列表

Question

我正在使用这个包https://github.com/zircote/swagger-php来编译swagger注解，并且很难创建一个可重复使用的参数列表。我可以重用单个参数，如下所示

/**
      * @OA\Get(
      *     path="/api/v2/seasons/{season_id}",
      *     description="Show season(s).",
      *     summary="List season(s) from comma separated id list",
      *     tags={"seasons"},
      *     security = { { "basicAuth": {} } },
      *     @OA\Parameter(
      *        name="id", in="path",required=true, @OA\Schema(type="integer")
      *     ),
      *     @OA\Parameter(ref="#/components/parameters/max-child-depth"),
      *     @OA\Parameter(ref="#/components/parameters/sort-by"),
      *     @OA\Parameter(ref="#/components/parameters/sort-order"),
      *     @OA\Parameter(ref="#/components/parameters/page"),
      *     @OA\Parameter(ref="#/components/parameters/page-size"),
      *     @OA\Parameter(ref="#/components/parameters/CatalogHeader"),
      *     @OA\Parameter(ref="#/components/parameters/SiteHeader"),
      *     @OA\Parameter(ref="#/components/parameters/AcceptLangHeader"),
      *     @OA\Parameter(ref="#/components/parameters/DebugHeader"),
      *     @OA\Response(response=200, ref="#/components/responses/200",
      *         @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/SeasonResponse"))
      *     ),
      *     @OA\Response(response=404, ref="#/components/responses/404"),
      *
      * )
      */

但我真正想要的是如下所示，因为我可以在每个路由注释定义中重用该标头和全局查询字符串参数的列表。

/**
      * @OA\Get(
      *     path="/api/v2/seasons/{season_id}",
      *     description="Show season(s).",
      *     summary="List season(s) from comma separated id list",
      *     tags={"seasons"},
      *     security = { { "basicAuth": {} } },
      *     @OA\Parameter(
      *        name="id", in="path",required=true, @OA\Schema(type="integer")
      *     ),
      *     parameters={ref="#/components/<IDK EXACTLY WHAT SECTION>/<but this would be a reusable param list>"},
      *     @OA\Response(response=200, ref="#/components/responses/200",
      *         @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/SeasonResponse"))
      *     ),
      *     @OA\Response(response=404, ref="#/components/responses/404"),
      *
      * )
      */

我试图在我的全局组件定义文件中创建一个@Link注释，但是当我使用它时，它不起作用。这似乎不是那个注解的正确用法。此外，对于这个GET路由，uri有一个参数，因此id仍然需要能够指定特定于此路由的参数，而且还需要附加全局参数的列表。

Answer 1

要引用参数，必须使用参数。

/**
 * @OA\Parameter(
 *      parameter="general--page",
 *      in="query",
 *      name="page",
 *      description="The current page for the result set, defaults to *1*",
 *      @OA\Schema(
 *          type="integer",
 *          default=1,
 *      )
 * )
 */

然后你可以重用它们

/**
 * @OA\Get(
 *     path="/api/assets/getall",
 *     operationId="getAssets",
 *     tags={"Assets"},
 *     summary="Get all Assets",
 *     description="Fetches all the Asset records",
 *     @OA\Parameter(
 *          ref="#/components/parameters/asset--limit",
 *          ref="#/components/parameters/general--page",
 *          ref="#/components/parameters/asset--updated_on",
 *     ),
 *     @OA\Response(
 *          ref="success",
 *          response=200,
 *          description="OK",
 *          @OA\JsonContent(ref="#/components/schemas/standardResponse"),
 *      ),
 * )
 */

Answer 2

不确定@ionut-plesca在这里是否完全正确。我认为你必须这样做：

/**
 * @OA\Get(
 *     path="/api/assets/getall",
 *     operationId="getAssets",
 *     tags={"Assets"},
 *     summary="Get all Assets",
 *     description="Fetches all the Asset records",
 *     @OA\Parameter(
 *          ref="#/components/parameters/asset--limit"
 *     ),
 *     @OA\Parameter(
 *          ref="#/components/parameters/general--page"
 *     ),
 *     @OA\Parameter(
 *          ref="#/components/parameters/asset--updated_on"
 *     ),
 *     @OA\Response(
 *          ref="success",
 *          response=200,
 *          description="OK",
 *          @OA\JsonContent(ref="#/components/schemas/standardResponse"),
 *      ),
 * )
 */

否则，ref似乎每次都会被覆盖。