对于 OpenAPI (swagger-php)，如何自动生成查询参数？答案

【问题标题】：For OpenAPI (swagger-php), how do I auto generate query parameters?对于 OpenAPI (swagger-php)，如何自动生成查询参数？
【发布时间】：2019-03-23 17:29:29
【问题描述】：

我正在编写 OpenAPI 规范并尝试从请求路由/路径的注释中自动（使用 swagger-php）生成我可能的查询参数。我知道我可以为每条路由输入所有可能的参数选项，但我确实需要能够使用注释自动从类的属性中生成可能的参数，就像我可以为请求正文做的那样。（我们将拥有大量的类/路径，并且除非它们像请求正文/JsonContent 那样生成，否则很可能不会发生这种情况。这可以通过 swagger-php 甚至是一般的 OpenAPI 实现吗？

我让它与 put 和请求正文一起使用，但是对于仍然使用类属性的 get 请求，我该如何做呢？

我可以为请求正文执行此操作：

    /**
     * @return Response
     *
     * * @OA\Put(
     *     path="/persons",
     *     tags={"Person"},
     *     @OA\RequestBody(
     *          request="person",
     *          required=false,
     *          description="Optional Request Parameters for Querying",
     *          @OA\JsonContent(ref="#/components/schemas/Person")
     *      ),
     *     @OA\Response(
     *          response="200",
     *          description="Returns matching Person Object",
     *          @OA\JsonContent(
     *              type="array",
     *              @OA\Items(ref="#/components/schemas/Person")
     *          )
     *     )
     * )
     */

写出 30 多个类的每个参数将无法维护：

     /** @OA\Get(
     *     path="/events",
     *     tags={"Events"},
     *     @OA\Parameter(
     *          name="eventID",
     *          in="query",
     *          required=false,
     *          description="The event ID specific to this event",
     *          @OA\Schema(
     *              type="string"
     *          ),
     *     ),
    *
   * ....etc

【问题讨论】：

不要走那条路。注释行往往会克服它们描述的方法的大小，并且语言不是最具表现力的。开发人员往往讨厌那些不可读的代码。
我实际上是主要开发人员（目前），并且觉得将它放在 cmets 中意味着它实际上可能保持最新。这就是为什么我试图像使用请求正文一样从属性中自动提取查询参数。这至少应该保证以最小的努力保持零件状态是最新的，对吧？你是说它不能自动完成吗？或者只是你不会推荐它？无论如何，你会推荐什么？

标签： php swagger openapi swagger-php

【解决方案1】：

Swagger-PHP 需要注释来记录查询参数。您可以通过添加可以使用$ref="#/components/parameters/PARAM_NAME" 引用的顶级@OA\Parameter 注释在一定程度上减少代码重复，如here 和here 所示。

/**
 * @OA\Parameter(
 *   parameter="eventID_in_query",
 *   name="eventID",
 *   description="The event ID specific to this event",
 *   @OA\Schema(
 *     type="string"
 *   ),
 *   in="query",
 *   required=false
 * )
 */

...

     /** @OA\Get(
     *     path="/events",
     *     tags={"Events"},
     *     @OA\Parameter(ref="#/components/parameters/eventID_in_query"),

【讨论】：