For OpenAPI (swagger-php), how do I auto generate query parameters?

Question

I am writing an OpenAPI spec and trying to generate my possible query parameters automatically (using swagger-php) from the annotations for a request route/path. I know that I can just type out all possible parameter options for each route, but I really need to be able to generate the possible parameters from the properties of a class automatically using annotations like I can do for the request body. (We will have tons of classes/paths and keeping it up to date most likely won't happen unless they are generated like the request body/JsonContent can be. Is this possible with swagger-php or even OpenAPI in general?

I got this to work with the put and the request body, but how do I do it for a get request that still uses the properties of the class?

I can do this for the request body:

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

Writing out each parameter for 30+ classes will not be maintainable:

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

Don't take that path. The annotation lines tend to overcome the size of the method they describe, and the language is not the most expressive. The developers tend to hate that code as is not readable. — Alex
I'm actually the main developer (for now) and feel like having it in the comments means it may actually stay up to date. That's why I'm trying to pull the query params automatically from the properties like I can with the request body. That should at least guarantee that part status up to date with minimal effort, right? Are you saying that it can't be done automatically though? Or just that you wouldn't recommend it? Regardless, what would you recommended then? — Joey Overby

Helen Helen · Accepted Answer · 2019-03-25T16:47:43

Swagger-PHP requires annotations to document the query parameters. You can reduce code duplication somewhat by adding top-level @OA\Parameter annotations that can be referenced using $ref="#/components/parameters/PARAM_NAME", as shown here and 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"),

For OpenAPI (swagger-php), how do I auto generate query parameters?

1 Answers