Non-Primitive, Non-Scalar HTTP Values
How can standard HTTP values that are non-primitive, non-scalar be documented in OpenAPI? They most often occur in HTTP header fields, but they occasionally occur in the path or query string too. There appears to be no documentation or coverage for these scenarios. Are these a gap or omission from the specification?
A few examples include:
- Accept (with quality) (ex: Accept: application/json; q=0.8, application/xml, application/problem+json)
- Range (ex: Range: bytes=0-99)
- Content-Disposition (ex: Content-Disposition: attachment; filename=example.txt)
- Link (ex: Link: <https://my.api.com/swagger.json>; rel="openapi" type="application/json")
There are other cases as well. Some values in the OData protocol have specific value formats that seemingly cannot be described by OpenAPI. Arrays, for example, must be encoded with surrounding '[' and ']'.
While an argument can be made that these values are objects and can be represented in the schema, there doesn't seem to be a way to control or define their serialization and deserialization. A well-known HTTP header cannot be represented in another format such as JSON nor are the values just text. A regular expression might be a way to enforce the format, but it is still a poor representation in the schema and UI.
Perhaps I've missed something in the specifications or documentation. Any thoughts or suggestions are appreciated.
