Swagger-php: Array as GET query parameter

[kamil-kielczewski]

Using this example (GET /pets) I create following code

    /* @OA\Get(
     *      path="/api/projects/{projectId}/stat",
     *      tags={"statistics"},
     *      description="some statistics",
     *      @OA\Parameter(
     *          name="category",
     *          description="array of category numbers",
     *          in="query",     
     *          @OA\Schema( 
     *              type="array", 
     *              @OA\Items( type="enum", enum={1,2,3,4,5,6,7,8,9} ),
     *          ),
     *          style="form"
     *      ),
     *       @OA\Response(response="200", description="Ok"),
    */

Swagger UI produce following request from it:

http://test.local/api/projects/120/stat?category=1&category=2

Which is wrong. So I correct it by chagne name="category" to name="category[]" and remove style=form:

     *      @OA\Parameter(
     *          name="category[]",
     *          description="array of category numbers",
     *          in="query",     
     *          @OA\Schema( 
     *              type="array", 
     *              @OA\Items( type="enum", enum={1,2,3,4,5,6,7,8,9} ),
     *              example={1,2} 
     *          )
     *      ),

And now I get proper link:

http://test.local/api/projects/120/stat?category[]=1&category[]=2

However, if we are purists, the parameter name should be category not category[]

[bfanger]

That category[] in the url is interpreted as an array is non-standard, PHP specific behavior.

The OpenApi spec is backend language agnostic.
The current behavior is correct.

[kamil-kielczewski]

Ok, I see we cannot automagically correct in swagger-php because swagger-UI is language independent (no php) - so we only can use above workaround.

[kamil-kielczewski]

Hm i read something about this problem but here people say that passing arrays as url parameters is framework dependent (!) and there are no standards at all(!) . So OpenApi has his own standards?

[bfanger]

OpenApi allows you to document different methods: https://swagger.io/docs/specification/serialization/
So you can describe the method the api uses, in php's case you'd document it with the [] suffux

[kamil-kielczewski]

hm... so te question is how to do it using swagger-php - for me solution is non-trivial :(

It is possible to add to swagger-php such "configuration" that "turn on" php arrays in OpenAPI ? Arrays are part of php which are used very often by many developers... this feature will be very usefull.

[bfanger]

Swagger-php is written in a way you can register your own processors which operate on the annotation tree.

If you'll write a plugin i'll gladly link to it on the related projects page

[kamil-kielczewski]

I see that you don't have time - its OK I understand.

I think the better Idea will be to write proper push request by me which solve this issue (plugin is not good - this should be build-in because arrays passing in GET query are used very often so they should work right "out of the box"). However I don't have time too :P to learn inside of swagger-php and swagger specification - and this is MINOR bug because i give workaround in description... may be some good guy from the future fix it... :P

[rodrigovive]

May be you need explode=false