describe caveats with union parameter types

[rafalkrupinski]

When declaring response types, some pairs of types, when used in Union in response headers, and sometimes in JSON bodies, are ambiguous:

• for Annotated[str | list[str], ${any no-explode param}], a scalar value can be interpreted as str or a single element `list[str].
• for Annotated[list[str] | dict[str, str], ${any no-explode param}], raw value name,value can be interpreted as ['name', 'value'] or {'name':'value'}.
• for str | ${any other scalar}
  • In case of headers, all scalar values are syntactically strings, so it's only possible to tell them apart by trying each type argument of Union. Pydantic will attempt each type from left to right and stop at first successful validation. When generating code, bare string should be moved to the end in such case.
  • in case of JSON body, primitive python types are serialized without quotes, but other scalar types supported by pydantic are simple strings.
• for Union[float, int] or Union[int, float] integral values serialized as float (e.g. 2.0) will be interpreted depending on order of type arguments.

When generating code, most of these problems can be avoided by re-ordering types, but warnings/errors are still needed for human authors.