php - 是否可以在 PHP 中创建可重用的 swagger 模板？

Question

我有一个相当大的 API，大多数端点共享相同的参数。
有什么办法可以制作一个可以简单重用的swagger模板，而不是每次都打字:

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

我会输入类似的内容:

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

我使用 NelmioApiDocBundle 在 Symfony (PHP) 中使用 Swagger

Answer 1

是的，这是可能的，您需要创建分页作为定义:

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

然后使用以下方法调用它:

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

例如:

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