salvo_oapi/extract/parameter/
query.rs

1use std::fmt::{self, Debug, Display, Formatter};
2use std::ops::{Deref, DerefMut};
3
4use salvo_core::extract::{Extractible, Metadata};
5use salvo_core::http::ParseError;
6use salvo_core::{Depot, Request};
7use serde::{Deserialize, Deserializer};
8
9use crate::endpoint::EndpointArgRegister;
10use crate::{Components, Operation, Parameter, ParameterIn, ToSchema};
11
12/// Represents the parameters passed by the URI path.
13pub struct QueryParam<T, const REQUIRED: bool = true>(Option<T>);
14impl<T> QueryParam<T, true> {
15    /// Consumes self and returns the value of the parameter.
16    pub fn into_inner(self) -> T {
17        self.0.expect("`QueryParam<T, true>` into_inner get `None`")
18    }
19}
20impl<T> QueryParam<T, false> {
21    /// Consumes self and returns the value of the parameter.
22    pub fn into_inner(self) -> Option<T> {
23        self.0
24    }
25}
26
27impl<T> Deref for QueryParam<T, true> {
28    type Target = T;
29
30    fn deref(&self) -> &Self::Target {
31        self.0
32            .as_ref()
33            .expect("`QueryParam<T, true>` defref get `None`")
34    }
35}
36impl<T> Deref for QueryParam<T, false> {
37    type Target = Option<T>;
38
39    fn deref(&self) -> &Self::Target {
40        &self.0
41    }
42}
43
44impl<T> DerefMut for QueryParam<T, true> {
45    fn deref_mut(&mut self) -> &mut Self::Target {
46        self.0
47            .as_mut()
48            .expect("`QueryParam<T, true>` defref_mut get `None`")
49    }
50}
51impl<T> DerefMut for QueryParam<T, false> {
52    fn deref_mut(&mut self) -> &mut Self::Target {
53        &mut self.0
54    }
55}
56
57impl<'de, T, const R: bool> Deserialize<'de> for QueryParam<T, R>
58where
59    T: Deserialize<'de>,
60{
61    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
62    where
63        D: Deserializer<'de>,
64    {
65        T::deserialize(deserializer).map(|value| Self(Some(value)))
66    }
67}
68
69impl<T: Debug, const R: bool> Debug for QueryParam<T, R> {
70    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
71        self.0.fmt(f)
72    }
73}
74
75impl<T: Display> Display for QueryParam<T, true> {
76    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
77        self.0
78            .as_ref()
79            .expect("`QueryParam<T, true>` as_ref get `None`")
80            .fmt(f)
81    }
82}
83
84impl<'ex, T> Extractible<'ex> for QueryParam<T, true>
85where
86    T: Deserialize<'ex>,
87{
88    fn metadata() -> &'static Metadata {
89        static METADATA: Metadata = Metadata::new("");
90        &METADATA
91    }
92    #[allow(refining_impl_trait)]
93    async fn extract(_req: &'ex mut Request, _depot: &'ex mut Depot) -> Result<Self, ParseError> {
94        panic!("query parameter can not be extracted from request")
95    }
96    #[allow(refining_impl_trait)]
97    async fn extract_with_arg(
98        req: &'ex mut Request,
99        _depot: &'ex mut Depot,
100        arg: &str,
101    ) -> Result<Self, ParseError> {
102        let value = req.query(arg).ok_or_else(|| {
103            ParseError::other(format!(
104                "query parameter {arg} not found or convert to type failed"
105            ))
106        })?;
107        Ok(Self(value))
108    }
109}
110impl<'ex, T> Extractible<'ex> for QueryParam<T, false>
111where
112    T: Deserialize<'ex>,
113{
114    fn metadata() -> &'static Metadata {
115        static METADATA: Metadata = Metadata::new("");
116        &METADATA
117    }
118    #[allow(refining_impl_trait)]
119    async fn extract(_req: &'ex mut Request, _depot: &'ex mut Depot) -> Result<Self, ParseError> {
120        panic!("query parameter can not be extracted from request")
121    }
122    #[allow(refining_impl_trait)]
123    async fn extract_with_arg(
124        req: &'ex mut Request,
125        _depot: &'ex mut Depot,
126        arg: &str,
127    ) -> Result<Self, ParseError> {
128        Ok(Self(req.query(arg)))
129    }
130}
131
132impl<T, const R: bool> EndpointArgRegister for QueryParam<T, R>
133where
134    T: ToSchema,
135{
136    fn register(components: &mut Components, operation: &mut Operation, arg: &str) {
137        let parameter = Parameter::new(arg)
138            .parameter_in(ParameterIn::Query)
139            .description(format!("Get parameter `{arg}` from request url query."))
140            .schema(T::to_schema(components))
141            .required(R);
142        operation.parameters.insert(parameter);
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use assert_json_diff::assert_json_eq;
149    use salvo_core::test::TestClient;
150    use serde_json::json;
151
152    use super::*;
153
154    #[test]
155    fn test_required_query_param_into_inner() {
156        let param = QueryParam::<String, true>(Some("param".to_owned()));
157        assert_eq!("param".to_owned(), param.into_inner());
158    }
159
160    #[test]
161    fn test_required_query_param_deref() {
162        let param = QueryParam::<String, true>(Some("param".to_owned()));
163        assert_eq!(&"param".to_owned(), param.deref())
164    }
165
166    #[test]
167    fn test_required_query_param_deref_mut() {
168        let mut param = QueryParam::<String, true>(Some("param".to_owned()));
169        assert_eq!(&mut "param".to_owned(), param.deref_mut())
170    }
171
172    #[test]
173    fn test_query_param_into_inner() {
174        let param = QueryParam::<String, false>(Some("param".to_owned()));
175        assert_eq!(Some("param".to_owned()), param.into_inner());
176    }
177
178    #[test]
179    fn test_query_param_deref() {
180        let param = QueryParam::<String, false>(Some("param".to_owned()));
181        assert_eq!(&Some("param".to_owned()), param.deref())
182    }
183
184    #[test]
185    fn test_query_param_deref_mut() {
186        let mut param = QueryParam::<String, false>(Some("param".to_owned()));
187        assert_eq!(&mut Some("param".to_owned()), param.deref_mut())
188    }
189
190    #[test]
191    fn test_query_param_deserialize() {
192        let param = serde_json::from_str::<QueryParam<String, true>>(r#""param""#).unwrap();
193        assert_eq!(param.0.unwrap(), "param");
194    }
195
196    #[test]
197    fn test_query_param_debug() {
198        let param = QueryParam::<String, true>(Some("param".to_owned()));
199        assert_eq!(format!("{param:?}"), r#"Some("param")"#);
200    }
201
202    #[test]
203    fn test_query_param_display() {
204        let param = QueryParam::<String, true>(Some("param".to_owned()));
205        assert_eq!(format!("{param}"), "param");
206    }
207
208    #[test]
209    fn test_required_query_param_metadata() {
210        let metadata = QueryParam::<String, true>::metadata();
211        assert_eq!("", metadata.name);
212    }
213
214    #[tokio::test]
215    #[should_panic]
216    async fn test_required_query_prarm_extract() {
217        let mut req = Request::new();
218        let mut depot = Depot::new();
219        let _ = QueryParam::<String, true>::extract(&mut req, &mut depot).await;
220    }
221
222    #[tokio::test]
223    async fn test_required_query_prarm_extract_with_value() {
224        let req = TestClient::get("http://127.0.0.1:5801").build_hyper();
225        let schema = req.uri().scheme().cloned().unwrap();
226        let mut req = Request::from_hyper(req, schema);
227        req.queries_mut()
228            .insert("param".to_owned(), "param".to_owned());
229        let mut depot = Depot::new();
230        let result =
231            QueryParam::<String, true>::extract_with_arg(&mut req, &mut depot, "param").await;
232        assert_eq!(result.unwrap().0.unwrap(), "param");
233    }
234
235    #[tokio::test]
236    #[should_panic]
237    async fn test_required_query_prarm_extract_with_value_panic() {
238        let req = TestClient::get("http://127.0.0.1:5801").build_hyper();
239        let schema = req.uri().scheme().cloned().unwrap();
240        let mut req = Request::from_hyper(req, schema);
241        let mut depot = Depot::new();
242        let result =
243            QueryParam::<String, true>::extract_with_arg(&mut req, &mut depot, "param").await;
244        assert_eq!(result.unwrap().0.unwrap(), "param");
245    }
246
247    #[test]
248    fn test_query_param_metadata() {
249        let metadata = QueryParam::<String, false>::metadata();
250        assert_eq!("", metadata.name);
251    }
252
253    #[tokio::test]
254    #[should_panic]
255    async fn test_query_prarm_extract() {
256        let mut req = Request::new();
257        let mut depot = Depot::new();
258        let _ = QueryParam::<String, false>::extract(&mut req, &mut depot).await;
259    }
260
261    #[tokio::test]
262    async fn test_query_prarm_extract_with_value() {
263        let req = TestClient::get("http://127.0.0.1:5801").build_hyper();
264        let schema = req.uri().scheme().cloned().unwrap();
265        let mut req = Request::from_hyper(req, schema);
266        req.queries_mut()
267            .insert("param".to_owned(), "param".to_owned());
268        let mut depot = Depot::new();
269        let result =
270            QueryParam::<String, false>::extract_with_arg(&mut req, &mut depot, "param").await;
271        assert_eq!(result.unwrap().0.unwrap(), "param");
272    }
273
274    #[tokio::test]
275    #[should_panic]
276    async fn test_query_prarm_extract_with_value_panic() {
277        let req = TestClient::get("http://127.0.0.1:5801").build_hyper();
278        let schema = req.uri().scheme().cloned().unwrap();
279        let mut req = Request::from_hyper(req, schema);
280        let mut depot = Depot::new();
281        let result =
282            QueryParam::<String, false>::extract_with_arg(&mut req, &mut depot, "param").await;
283        assert_eq!(result.unwrap().0.unwrap(), "param");
284    }
285
286    #[test]
287    fn test_query_param_register() {
288        let mut components = Components::new();
289        let mut operation = Operation::new();
290        QueryParam::<String, false>::register(&mut components, &mut operation, "arg");
291
292        assert_json_eq!(
293            operation,
294            json!({
295                "parameters": [
296                    {
297                        "name": "arg",
298                        "in": "query",
299                        "description": "Get parameter `arg` from request url query.",
300                        "required": false,
301                        "schema": {
302                            "type": "string"
303                        }
304                    }
305                ],
306                "responses": {}
307            })
308        )
309    }
310}
salvo_oapi/extract/parameter/query.rs

salvo_oapi/extract/parameter/
query.rs
