Is it possible to create reusable swagger templates in PHP?

user_5329722 0
Viewed 132

I have a quite large API and most of the endpoints share the same parameters. Is there any way to make a swagger template that can be simply reused, so instead of typing every time:

     * @SWG\Parameter(
     *     name="page",
     *     in="query",
     *     type="integer",
     *     required=true,
     * )
     * @SWG\Parameter(
     *     name="perPage",
     *     in="query",
     *     type="integer",
     *     required=true,
     * )
     * @SWG\Parameter(
     *     name="orderBy",
     *     in="query",
     *     type="string",
     *     required=true,
     * )
     * @SWG\Parameter(
     *     name="orderDir",
     *     in="query",
     *     type="string",
     *     enum={"asc", "desc"},
     *     required=true,
     * )

I would type something like:

    * @SWG\Template("pagination")
    * @SWG\Template("sorting")

I am using Swagger in Symfony (PHP) using NelmioApiDocBundle

symfony swagger php
1 Answers

Yes it is possible, you will need to create the pagination as a definition:

/**
 * @SWG\Parameter(
 *      name="perPage",
 *      in="query",
 *      type="integer",
 *      required=false
 * )
 */

Then call it using:

 * @SWG\Parameter(
 *     ref="#/parameters/perPage"
 * ),

For example:

/**
 * @SWG\Get(
 *     path="/api/v1/users",
 *     @SWG\Parameter(
 *          ref="#/parameters/page"
 *     ),
 *     @SWG\Parameter(
 *          ref="#/parameters/perPage"
 *     ),
 *     @SWG\Parameter(
 *          ref="#/parameters/orderBy"
 *     ),
 *     @SWG\Parameter(
 *          ref="#/parameters/orderDir"
 *     ),
 *     @SWG\Response(response="200", description="Return something")
 * )
 *
 * @SWG\Parameter(
 *      name="page",
 *      in="query",
 *      type="integer",
 *      required=false
 * )
 *
 * @SWG\Parameter(
 *      name="perPage",
 *      in="query",
 *      type="integer",
 *      required=false
 * )
 *
 * @SWG\Parameter(
 *      name="orderBy",
 *      in="query",
 *      type="string",
 *      required=false
 * )
 *
 * @SWG\Parameter(
 *      name="orderDir",
 *      in="query",
 *      type="string",
 *      required=false
 * )
*/
user_109275710
Related