Parameter examples is still far from ideal.

[mpodlasin]

There is still some awkward spots here IMHO, so I would like to discuss it.

(Note that for the sake of discussion I simplified some types here)

A single parameter of type T can have an example in 4 places:

• parameter.example of type T
• parameter.examples of {[index: string]: { value: T}}
• parameter.schema.example of type T
• parameter.schema.examples of type T[]

We do few major things with those in http-spec:

1. We place parameter.schema.example in `parameter.schema.examples' (essentially overwriting it if exists, I believe?)
2. We place parameter.example in parameter.schema.example (again, overwriting, if the latter exists)
3. After my change we place parameter.example in parameter.examples (by appending, not overwriting)

All those things combined lead to funny behaviour.

To make sure I gathered all possible examples, I have to do [...parameter.examples, ...parameter.schema.examples]. This is a problem in itself btw, I shouldn't be forced to concatenate stuff to get all the possible examples.

But on top of that, because parameter.example lands both in parameter.examples (by 3) and parameter.schema.examples (by 2 followed by 1), it leads to having doubled examples on the list, when parameter.example is utilised in the original schema.

Proposal

Therefore I propose to cut this complex logic, and simply put all the parameters described above on a single parameters.examples list, while leaving the schema untouched. It would essentially concatenate all 4 example types into one. http-spec users should only access examples via parameters.examples and all examples should be available there.

The one problem that comes to my mind would be naming. Especially names from parameter.schema.examples would have to be generated, as this property is just a list of values. I guess something like schema example 1... could be generated automatically.