Question

我正在编写OpenAPI规范，并尝试根据请求路由/路径的注释自动（使用swagger-php）生成可能的查询参数。我知道我可以为每个路由键入所有可能的参数选项，但是我确实确实需要能够像使用请求正文一样使用注释从类的属性中自动生成可能的参数。（我们将拥有大量的类/路径，并且除非有类似请求正文/ JsonContent这样的生成方式，否则很可能不会使其保持最新状态。通常使用swagger-php或什至OpenAPI都可以做到这一点吗？

我把它与put和request主体一起使用，但是如何为仍然使用该类属性的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

Answer 1

Swagger-PHP需要注释来记录查询参数。您可以通过添加可以使用@OA\Parameter引用的顶级$ref="#/components/parameters/PARAM_NAME"注释来减少代码重复，如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"),

对于OpenAPI（swagger-php），如何自动生成查询参数？

1 个答案: