Explode doesn't seem to work as expected for query string parameters

[breis-sa]

First and foremost, thank you for the great gem, it really speed things up when it comes to API request validation.

Now about the issue I found - which might not be an issue and just my misunderstanding of how to use the gem/OpenAPI spec correctly - it seems that the explode option is not working correctly for query string parameters.

According to the OpenAPI spec, when style is form and explode is true, objects should generate separate parameters for each array item or object property as seen in the example below:

So I declared the following definition for my endpoint. I'm basically trying to build an endpoint that accepts mutually exclusive query string parameters (like in this example)

  /my-endpoint/foo/bar/baz:
    parameters:
      # path parameters here
    get:
      summary: Lorem ipsum
      operationId: myEndpointFooBarBaz
      parameters:
        - in: query
          name: id
          style: form
          explode: true
          required: true
          schema:
            type: object
            oneOf:
              - properties:
                  role:
                    type: string
                required: [role]
              - properties:
                  firstName:
                    type: string
                required: [firstName]
      responses:
        # responses here

If I send the request as: /my-endpoint/foo/bar/baz?role=1234&firstName=John, I would expect to get back an error informing that request should match one of the valid schemas, but instead, I get back an error saying something like request is missing required parameters: id

[geemus]

@breis-sa glad to hear it's been helpful!

I don't personally have any experience with explode, maybe because I don't tend to use query params much. Looking at this code base and the one for the underlying parser, I found only a couple references to explode, which leads me to believe that you are correct that it basically isn't implemented at present.

Could you tell me a little bit more about what you are trying to accomplish? Are you trying to map to an existing API or is the design still being worked out? Is there a reason it has to be query params in particular (as opposed to say a POST with JSON body params)?

[breis-sa]

@geemus I was basically trying to add a new endpoint to our API for listing a specific resource (and following the usual RESTful guidelines it should be a GET request). This endpoint however, needs to accept two different query string parameters and due to our requirements, these parameters are mutually exclusive.
So the url with the query string would be something like /entities?param1=foo or /entities?param2=bar. /entities?param1=foo&param2=bar is considered a bad request.
While it's fairly easy to express this mutually exclusive behavior using oneOf in JSON schemas, the OpenAPI specs require me to declare query params separately. That's when I though of using explode in a similar fashion to what is in the screenshot from my previous comment.

[geemus]

@breis-sa A different way to express that which might be easier to express and manage would be something roughly like:

/entities?key=firstName&value=Jill

Then you can make key/value each required, and can specify an enum of the allowed keys.

Would that satisfy your use case?

[breis-sa]

@geemus unfortunately I can't do that as it would go against the standard our API follows in other endpoints

[geemus]

@breis-sa fair enough, though I might argue that if it does something distinct it's probably allowed to have a somewhat different interface, that's kind of neither here nor there.

This is the first time I've encountered or really thought about explode. Looking at the codebase here and the underlying openapi parser, there is only one mention of it (and it seems to be to indicate that it could be a value in the schema, with not logic associated with it).

So it does seem that this would require some new implementation. I don't really have capacity to take that on, but I'd certainly be happy to support it if you want to make an attempt. Thanks!

[ahx]

Hi. I have build a gem openapi_parameters about these intricate details of OpenAPI 3 parameter parsing. It can handle all sorts of explode/style/deepObject variants. This one is probably included. It replaces the default parsing of query parameters used by Rack::Request#params. If you want to check that out I am happy to help. https://github.com/ahx/openapi_parameters