1+ #![ allow( deprecated) ]
2+
13use axum_core:: __composite_rejection as composite_rejection;
24use axum_core:: __define_rejection as define_rejection;
35use axum_core:: extract:: FromRequestParts ;
@@ -8,72 +10,16 @@ use serde_core::de::DeserializeOwned;
810///
911/// `T` is expected to implement [`serde::Deserialize`].
1012///
11- /// # Differences from `axum::extract::Query`
12- ///
13- /// This extractor uses [`serde_html_form`] under-the-hood which supports multi-value items. These
14- /// are sent by multiple `<input>` attributes of the same name (e.g. checkboxes) and `<select>`s
15- /// with the `multiple` attribute. Those values can be collected into a `Vec` or other sequential
16- /// container.
17- ///
18- /// # Example
19- ///
20- /// ```rust,no_run
21- /// use axum::{routing::get, Router};
22- /// use axum_extra::extract::Query;
23- /// use serde::Deserialize;
24- ///
25- /// #[derive(Deserialize)]
26- /// struct Pagination {
27- /// page: usize,
28- /// per_page: usize,
29- /// }
30- ///
31- /// // This will parse query strings like `?page=2&per_page=30` into `Pagination`
32- /// // structs.
33- /// async fn list_things(pagination: Query<Pagination>) {
34- /// let pagination: Pagination = pagination.0;
13+ /// # Deprecated
3514///
36- /// // ...
37- /// }
15+ /// This extractor used to use a different deserializer under-the-hood but that
16+ /// is no longer the case. Now it only uses an older version of the same
17+ /// deserializer, purely for ease of transition to the latest version.
18+ /// Before switching to `axum::extract::Form`, it is recommended to read the
19+ /// [changelog for `serde_html_form v0.3.0`][changelog].
3820///
39- /// let app = Router::new().route("/list_things", get(list_things));
40- /// # let _: Router = app;
41- /// ```
42- ///
43- /// If the query string cannot be parsed it will reject the request with a `400
44- /// Bad Request` response.
45- ///
46- /// For handling values being empty vs missing see the [query-params-with-empty-strings][example]
47- /// example.
48- ///
49- /// [example]: https://github.com/tokio-rs/axum/blob/main/examples/query-params-with-empty-strings/src/main.rs
50- ///
51- /// While `Option<T>` will handle empty parameters (e.g. `param=`), beware when using this with a
52- /// `Vec<T>`. If your list is optional, use `Vec<T>` in combination with `#[serde(default)]`
53- /// instead of `Option<Vec<T>>`. `Option<Vec<T>>` will handle 0, 2, or more arguments, but not one
54- /// argument.
55- ///
56- /// # Example
57- ///
58- /// ```rust,no_run
59- /// use axum::{routing::get, Router};
60- /// use axum_extra::extract::Query;
61- /// use serde::Deserialize;
62- ///
63- /// #[derive(Deserialize)]
64- /// struct Params {
65- /// #[serde(default)]
66- /// items: Vec<usize>,
67- /// }
68- ///
69- /// // This will parse 0 occurrences of `items` as an empty `Vec`.
70- /// async fn process_items(Query(params): Query<Params>) {
71- /// // ...
72- /// }
73- ///
74- /// let app = Router::new().route("/process_items", get(process_items));
75- /// # let _: Router = app;
76- /// ```
21+ /// [changelog]: https://github.com/jplatte/serde_html_form/blob/main/CHANGELOG.md#030
22+ #[ deprecated = "see documentation" ]
7723#[ cfg_attr( docsrs, doc( cfg( feature = "query" ) ) ) ]
7824#[ derive( Debug , Clone , Copy , Default ) ]
7925pub struct Query < T > ( pub T ) ;
@@ -140,14 +86,15 @@ composite_rejection! {
14086 /// Rejection used for [`Query`].
14187///
14288/// Contains one variant for each way the [`Query`] extractor can fail.
89+ [ deprecated = "because Query is deprecated" ]
14390 pub enum QueryRejection {
14491 FailedToDeserializeQueryString ,
14592 }
14693}
14794
14895/// Extractor that deserializes query strings into `None` if no query parameters are present.
14996///
150- /// Otherwise behaviour is identical to [`Query`].
97+ /// Otherwise behaviour is identical to [`Query`][axum::extract::Query] .
15198/// `T` is expected to implement [`serde::Deserialize`].
15299///
153100/// # Example
@@ -179,11 +126,6 @@ composite_rejection! {
179126///
180127/// If the query string cannot be parsed it will reject the request with a `400
181128/// Bad Request` response.
182- ///
183- /// For handling values being empty vs missing see the [query-params-with-empty-strings][example]
184- /// example.
185- ///
186- /// [example]: https://github.com/tokio-rs/axum/blob/main/examples/query-params-with-empty-strings/src/main.rs
187129#[ cfg_attr( docsrs, doc( cfg( feature = "query" ) ) ) ]
188130#[ derive( Debug , Clone , Copy , Default ) ]
189131pub struct OptionalQuery < T > ( pub Option < T > ) ;
0 commit comments