CODEWITHSUNDEEP
phplaravelswaggerlumen
rich
rich

Reputation: 367

How to define and use a reuseable parameter list for swagger in php

Im using this package https://github.com/zircote/swagger-php to compile swagger annotations and having a hard time creating a resuable list of parameters. I can reuse individual parameters like below 

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

but what id really like to is something like the following as i can reuse that list of headers and global query string parameters in each route annotation definition. 

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

Ive tried to create a @Link annotation in my global components definition file, but when i use it doesnt work. Doesnt seem like that is the correct usage for that annotation. Also for this GET route, the uri has a parameter, so id still need be able to specify the parameter specific to this route, but also append the list of global params.

Upvotes: 7

Views: 17525

Answers (2)

mikelovelyuk
mikelovelyuk

Reputation: 4152

Not sure if @ionut-plesca is completely correct here. I think you'd have to do:

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

Otherwise it seems ref is overwritten each time.

Upvotes: 6

Ionut Plesca
Ionut Plesca

Reputation: 61

To reference params you must use a parameter.

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

And then you can reuse them

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

Upvotes: 6

Related Questions