2026-09-29 · 6 min read · Rahul Chitturi
- openapi
- http
- api
OpenAPI tells clients how to turn a parameter value into path, query, header, or cookie text through style and explode. A generated SDK can emit comma-separated values while the server splits on pipes, or it can explode an object into brackets the gateway never parses.
The bug looks like a random 400 because both sides believe they followed the specification. The wire string is the contract; the parameter schema alone does not show how that string was built.
Write down location, style, and explode
For the failing operation, record the parameter location, name, schema, style, explode, allowReserved, and the raw request target or header value. Include the OpenAPI version and the generator that produced the client.
- Path parameters default to simple style.
- Query parameters commonly use form style.
- explode changes arrays and objects, not only objects.
- Reserved characters still need the encoding the location requires.
Compare one value on the wire
Pick a single array or object fixture and serialize it by hand from the specification, then compare that text with the captured request. Spaces, commas, brackets, and empty values are where generators diverge. Deep object query styles are not portable across every client.
Header and cookie parameters have additional restrictions. A value that is legal in a query string can be illegal or reinterpreted in a header if it contains separators the style assumes will be escaped.
Lock the fixture to both sides
Use Flashman's YAML/JSON converter for the OpenAPI document, the JSON formatter for the parameter example, the URL parser for the request target, and the case converter when names differ between the schema and the wire.
Test scalars, empty arrays, arrays with reserved characters, exploded and unexploded objects, missing optional parameters, headers, cookies, and at least one generated client against the server parser.