Query string parameter in swagger documentation not sent as array in request

Question

I am currently working on project using Symfony 4.3.4 and API platform v2.3.6.

I am facing 1 issue right now. Let’s say I send a GET request to an enpoint with a query string parameter called products because I send 1 or more product IDs.

I want to get the value of the products parameter in my controller as a PHP array.

So my request is

GET /my/endpoint?products[]=8f391c60-5467-4bf0-917f-e2151337fa7e&products[]=ddaa94e1-af79-4abf-9dfc-a28dd8077f45

In the controller I perform a dump:

dump($request->query->get("products"));

Then I get:

array:2 [
  0 => "8f391c60-5467-4bf0-917f-e2151337fa7e"
  1 => "ddaa94e1-af79-4abf-9dfc-a28dd8077f45"
]

As you can see the way I pass my product IDs like an array in the query string, I can retrieve the products parameter as a PHP array. My concern here, is the swagger documentation. Using this configuration in YAML:

collectionOperations:
    operation_name:
        method: get
        path: /my/endpoint
        controller: App\Controller\MyEndpointController
        swagger_context:
            summary: My summary
            description:
                My endpoint description
            responses:
                parameters:
                    -
                        in: query
                        name: products
                        description: "The products IDs parameter"
                        schema:
                            type: array
                            items:
                                type: "string"
                                example: "019fcd9b-beea-4791-8a59-d4e2d02427d6"

In the API documentation page when I choose Try it out I have to fill in all the parameters value included products. The problem is that products parameter appears as a text input.

If I remove the schema key in the yaml configuration of the parameter and I put type: array and items keys directly at the same level as in, name and description:

parameters:
    -
        in: query
        name: products
        description: "The products IDs parameter"
        type: array
        items:
            type: "string"
            example: "019fcd9b-beea-4791-8a59-d4e2d02427d6"

Then the products parameter appears with a button Add item. Each time I click on this button, I can fill a product ID to pass and that is fine. The problem is that when I click on Execute (still in the API documentation page) I have an error because API platform does not send the request with products parameter as a true array but as a string containing all product IDs separated by ,:

GET /my/endpoint?products=8f391c60-5467-4bf0-917f-e2151337fa7e,ddaa94e1-af79-4abf-9dfc-a28dd8077f45

and this is what I want:

GET /my/endpoint?products[]=8f391c60-5467-4bf0-917f-e2151337fa7e&products[]=ddaa94e1-af79-4abf-9dfc-a28dd8077f45

any idea about the way to achieve this with API platform?

Helen · Accepted Answer · 2019-09-24 10:13:58Z

4

The query parameter needs to be named products[] (with square brackets) and have the collectionFormat: multi attribute:

parameters:
  - in: query
    name: products[]
    type: array
    items:
      type: string
      format: uuid
    collectionFormat: multi
    # (Optional) Array example to display in Swagger UI
    x-example:
      - 8f391c60-5467-4bf0-917f-e2151337fa7e
      - ddaa94e1-af79-4abf-9dfc-a28dd8077f45

Note that query parameters in OpenAPI 2.0 do not support the example keyword, but some tools (such as Swagger UI) support the x-example extension to specify the example values for query parameters.

answered Sep 24, 2019 at 10:13

Helen

99.8k17 gold badges280 silver badges352 bronze badges

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

Collectives™ on Stack Overflow

Query string parameter in swagger documentation not sent as array in request

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