如何在 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"),
      *
      * )
      */

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

/**
      * @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每次都会被覆盖。