Improve documentation of axum_extra::extract::Query (#2517)

axum-extra/src/extract/query.rs

@@ -51,6 +51,33 @@ use std::fmt;
 /// example.
 ///
 /// [example]: https://github.com/tokio-rs/axum/blob/main/examples/query-params-with-empty-strings/src/main.rs
+///
+/// While `Option<T>` will handle empty parameters (e.g. `param=`), beware when using this with a
+/// `Vec<T>`. If your list is optional, use `Vec<T>` in combination with `#[serde(default)]`
+/// instead of `Option<Vec<T>>`. `Option<Vec<T>>` will handle 0, 2, or more arguments, but not one
+/// argument.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// use axum::{routing::get, Router};
+/// use axum_extra::extract::Query;
+/// use serde::Deserialize;
+///
+/// #[derive(Deserialize)]
+/// struct Params {
+///     #[serde(default)]
+///     items: Vec<usize>,
+/// }
+///
+/// // This will parse 0 occurrences of `items` as an empty `Vec`.
+/// async fn process_items(Query(params): Query<Params>) {
+///     // ...
+/// }
+///
+/// let app = Router::new().route("/process_items", get(process_items));
+/// # let _: Router = app;
+/// ```
 #[cfg_attr(docsrs, doc(cfg(feature = "query")))]
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Query<T>(pub T);

axum/src/extract/query.rs

@@ -42,6 +42,11 @@ use serde::de::DeserializeOwned;
 /// example.
 ///
 /// [example]: https://github.com/tokio-rs/axum/blob/main/examples/query-params-with-empty-strings/src/main.rs
+///
+/// For handling multiple values for the same query parameter, in a `?foo=1&foo=2&foo=3`
+/// fashion, use [`axum_extra::extract::Query`] instead.
+///
+/// [`axum_extra::extract::Query`]: https://docs.rs/axum-extra/latest/axum_extra/extract/struct.Query.html
 #[cfg_attr(docsrs, doc(cfg(feature = "query")))]
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Query<T>(pub T);