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

【问题标题】：How to define and use a reuseable parameter list for swagger in php如何在php中为swagger定义和使用可重用的参数列表
【发布时间】：2020-04-13 04:17:31
【问题描述】：

我正在使用这个包 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 仍然需要能够指定该路由特定的参数，还要附加全局参数列表。

【问题讨论】：

OpenAPI Specification doesn't have a way to $ref 一组参数，所以可能没有任何代码注释可以做到这一点。

标签： php laravel swagger lumen

【解决方案1】：

不确定@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 每次都会被覆盖。

【讨论】：

同意，至少 OA 3.0

【解决方案2】：

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

/**
 * @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"),
 *      ),
 * )
 */

【讨论】：