feat: extend the colection format rule (154) to support OpenAPI 3 (#439)

[maxim-tschumak]

Closes #439

[ghost]

👍

[tkrop]

I would stick to

== {SHOULD} Define Collection Format of Query Parameters

as minimal precise description.

[tkrop]

To simplify language I suggest the following text:

Sometimes, query parameters allow to provide a list of values, either by providing a comma-separated list (csv) or by repeating the parameter multiple times with different values (multi). The API specification should explicitly define one type as follows:

I think the following two sentences are optional:

In the Open API 3.0, the https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#style-values[`style: form] in combination with explode: true | false` is used.

In the Open API 2.0 the https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object[`collectionFormat: csv | multi`] is used.

[tkrop]

May be better

1. Open API 3.0 | Open API 2.0
2. The example can use key or param instead of parameter.
3. Multiple parameter instances => Multiple parameters.

[tkrop]

I'm still not sure whether we should restrict this to query parameters only. Shouldn't path or header parameters follow the same rule if used?

[whiskeysierra]

Headers maybe, but arrays in path segments sounds incredibly wrong to me.

[maxim-tschumak]

I also wouldn't do this for path parameters, but it sounds reasonable for headers.

[tkrop]

@whiskeysierra I agree, but the URI format is open to this, and if we cannot predict use cases here, my approach would to not restrict the application of the rule. The only result would be, that readers heaving the use case would not specify it, making it even harder to detect in a review.

[tkrop]

In reviews I have experienced, that at least some readers cannot apply this concept in Open API. So may be we should give them at least one very concrete example:

For Open API 3.0 a csv query parameter will look as follows:

parameters:
    - name: customer_ids
      in: query
      type: array
      style: form
      explode: false
      items:
        type: string

[whiskeysierra]

If it's explode: false shouldn't it be customer_ids then?

[maxim-tschumak]

@tkrop I would not include an example. It's clearly stated in the table which properties have to be set.
And if we decide to include an OpenAPI 3 example, we also have to include an OpenAPI 2 example. This will take too much space.

[whiskeysierra]

👍

[maxim-tschumak]

👍

[tkrop]

👍