Module query 

Query-parameter contract shared by the generated client, the generated server route, and the OpenAPI spec.

Why this module exists

The three consumers of a query parameter used to disagree. The client flattened the parameter to JSON and hand-rolled a query string; the server decoded with serde_urlencoded via axum::extract::Query; the spec described whatever the macro could infer from the Rust type at expansion time. Nothing reconciled them, so several shapes compiled cleanly and then failed on every request:

• a scalar parameter (count: u64) produced Query<u64>, and serde_urlencoded’s top-level deserializer only yields a map — a guaranteed 400 against a spec that advertised the parameter as valid;
• a Vec<T> field went out as repeated keys, which serde_urlencoded cannot collect into a sequence;
• a nested struct lost its outer key entirely during flattening.

The contract now

A query parameter is a struct deriving crate::QueryParams. Both ends encode and decode it with serde_html_form, which round-trips repeated keys as sequences, and the derive emits the parameter list the OpenAPI spec is built from — so the spec is generated from the same declaration the wire format is.

Each field’s leaf type must implement QueryScalar. That bound is what rejects nesting: a query string is a flat list of key/value pairs, and neither serde_html_form nor any other single-level codec can represent a sub-object unambiguously.

Structs

QueryParamSpec

One query parameter as it should appear in the OpenAPI document.

Traits

QueryParams

A struct usable as a REST query parameter.

QueryScalar

A type that can appear as a query-parameter value.

Functions

to_query_string

Serialize a query struct into a query string (no leading ?).