apisyouwonthate/style-guide

Semantic Rule: WTF Parameter Styles

philsturgeon opened this issue · 1 comments

philsturgeon commented 
format: oas3

Parameter styles, full of powerful footguns which are luckily too confusing to operate.

Screen Shot 2020-04-27 at 19 40 47

Doesn't look too confusing yet, but... enhance!

Screen Shot 2020-04-27 at 19 44 56

Wait what? enhance!

image

AAGGGH

Ok, so let's try and make some rules that look for invalid combinations so we can help users stumble towards a valid combination.

  1. Ensure "style" is set on a type which allows it.
  2. Ensure "style" is set on an in which allows it.
  3. Should we suggest people add an example for anything which contains a parameter style so the end users of whatever documentation tool will know what it's supposed to look like?
  4. Can we validate that example against the confusing combination of things if its passing those first two checks?!