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
– Alex, Commented Mar 24, 2019 at 0:21
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
– Joey Overby, Commented Mar 25, 2019 at 3:15

Helen · Accepted Answer · 2019-03-25 16:47:43Z

1

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"),

answered Mar 25, 2019 at 16:47

Helen

99.8k18 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related