oapi-codegen icon indicating copy to clipboard operation
oapi-codegen copied to clipboard

Document exploded form params

Open jamietanna opened this issue 1 year ago • 0 comments


- exploded, form style query arguments, which are the default argument format
  in OpenAPI 3.0 are undecidable. Say that I have two objects, one composed of
  the fields `(name=bob, id=5)` and another which has `(name=shoe, color=brown)`.
  The first parameter is named `person` and the second is named `item`. The
  default marshaling style for query args would result in
  `/path/?name=bob,id=5&name=shoe,color=brown`. In order to tell what belongs
  to which object, we'd have to look at all the parameters and try to deduce it,
  but we're lazy, so we didn't. Don't use exploded form style arguments if
  you're passing around objects which have similar field names. If you
  used unexploded form parameters, you'd have
  `/path/?person=name,bob,id,5&item=name,shoe,color,brown`, which an be
  parsed unambiguously.

- Parameters can be defined via `schema` or via `content`. Use the `content` form
  for anything other than trivial objects, they can marshal to arbitrary JSON
  structures. When you send them as cookie (`in: cookie`) arguments, we will
  URL encode them, since JSON delimiters aren't allowed in cookies.

jamietanna avatar Apr 20 '24 15:04 jamietanna