poem_openapi/
base.rs

1use std::{
2    collections::HashMap,
3    fmt::{self, Debug, Display},
4    future::Future,
5    ops::Deref,
6};
7
8use futures_util::FutureExt;
9use poem::{endpoint::BoxEndpoint, http::Method, Error, FromRequest, Request, RequestBody, Result};
10use serde::Serialize;
11
12use crate::{
13    payload::Payload,
14    registry::{
15        MetaApi, MetaMediaType, MetaOAuthScope, MetaParamIn, MetaRequest, MetaResponse,
16        MetaResponses, MetaSchemaRef, MetaWebhook, Registry,
17    },
18};
19
20/// The style of the passed parameter. See https://swagger.io/docs/specification/v3_0/serialization/ for details
21#[derive(Debug, Copy, Clone, Eq, PartialEq, Serialize)]
22#[serde(rename_all = "camelCase")]
23pub enum ParameterStyle {
24    /// Dot-prefixed values, also known as label expansion.
25    Label,
26    /// Semicolon-prefixed values, also known as path-style expansion.
27    Matrix,
28    /// Ampersand-separated values, also known as form-style query expansion.
29    Form,
30    /// Comma-separated values
31    Simple,
32    /// Space-separated array values. Has effect only for non-exploded arrays.
33    SpaceDelimited,
34    /// Pipeline-separated array values. Has effect only for non-exploded
35    /// arrays.
36    PipeDelimited,
37    /// Bracket-nested objects, e.g.
38    /// `paramName[prop1]=value1&paramName[prop2]=value2`
39    DeepObject,
40}
41
42/// API extractor types.
43#[derive(Debug, Copy, Clone, Eq, PartialEq)]
44pub enum ApiExtractorType {
45    /// A request object.
46    RequestObject,
47
48    /// A request parameter.
49    Parameter,
50
51    /// A security scheme.
52    SecurityScheme,
53
54    /// A poem extractor.
55    PoemExtractor,
56}
57
58#[doc(hidden)]
59#[derive(Clone)]
60pub struct UrlQuery(pub Vec<(String, String)>);
61
62impl Deref for UrlQuery {
63    type Target = Vec<(String, String)>;
64
65    fn deref(&self) -> &Self::Target {
66        &self.0
67    }
68}
69
70impl UrlQuery {
71    /// Returns all values with the specified name.
72    pub fn get_all<'a, 'b: 'a>(&'b self, name: &'a str) -> impl Iterator<Item = &'b String> + 'a {
73        self.0
74            .iter()
75            .filter(move |(n, _)| n == name)
76            .map(|(_, value)| value)
77    }
78
79    /// Returns the first value with the specified name.
80    pub fn get(&self, name: &str) -> Option<&String> {
81        self.get_all(name).next()
82    }
83}
84
85/// Options for the parameter extractor.
86#[derive(Clone)]
87pub struct ExtractParamOptions<T> {
88    /// The name of this parameter.
89    pub name: &'static str,
90
91    /// The default value of this parameter.
92    pub default_value: Option<fn() -> T>,
93
94    /// The example value of this parameter.
95    pub example_value: Option<fn() -> T>,
96
97    /// When this is `true`, parameter values of type array or object generate
98    /// separate parameters for each value of the array or key-value pair of the
99    /// map.
100    pub explode: bool,
101
102    /// The style of the parameter.
103    pub style: Option<ParameterStyle>,
104}
105
106impl<T> Default for ExtractParamOptions<T> {
107    fn default() -> Self {
108        Self {
109            name: "",
110            default_value: None,
111            example_value: None,
112            explode: true,
113            style: None,
114        }
115    }
116}
117
118/// Represents an OpenAPI extractor.
119///
120/// # Provided Implementations
121///
122/// - **Path&lt;T: Type>**
123///
124///    Extract the parameters in the request path into
125///    [`Path`](crate::param::Path).
126///
127/// - **Query&lt;T: Type>**
128///
129///    Extract the parameters in the query string into
130///    [`Query`](crate::param::Query).
131///
132/// - **Header&lt;T: Type>**
133///
134///    Extract the parameters in the request header into
135///    [`Header`](crate::param::Header).
136///
137/// - **Cookie&lt;T: Type>**
138///
139///    Extract the parameters in the cookie into
140///    [`Cookie`](crate::param::Cookie).
141///
142/// - **CookiePrivate&lt;T: Type>**
143///
144///    Extract the parameters in the private cookie into
145///    [`CookiePrivate`](crate::param::CookiePrivate).
146///
147/// - **CookieSigned&lt;T: Type>**
148///
149///    Extract the parameters in the signed cookie into
150///    [`CookieSigned`](crate::param::CookieSigned).
151///
152/// - **Binary&lt;T>**
153///
154///    Extract the request body as binary into
155///    [`Binary`](crate::payload::Binary).
156///
157/// - **Json&lt;T>**
158///
159///    Parse the request body in `JSON` format into
160///    [`Json`](crate::payload::Json).
161///
162/// - **PlainText&lt;T>**
163///
164///    Extract the request body as utf8 string into
165///    [`PlainText`](crate::payload::PlainText).
166///
167/// - **Any type derived from the [`ApiRequest`](crate::ApiRequest) macro**
168///
169///    Extract the complex request body derived from the `ApiRequest` macro.
170///
171/// - **Any type derived from the [`Multipart`](crate::Multipart) macro**
172///
173///    Extract the multipart object derived from the `Multipart` macro.
174///
175/// - **Any type derived from the [`SecurityScheme`](crate::SecurityScheme)
176///   macro**
177///
178///    Extract the authentication value derived from the `SecurityScheme`
179///    macro.
180///
181/// - **T: poem::FromRequest**
182///
183///    Use Poem's extractor.
184#[allow(unused_variables)]
185pub trait ApiExtractor<'a>: Sized {
186    /// The type of API extractor.
187    const TYPES: &'static [ApiExtractorType];
188
189    /// If it is `true`, it means that this parameter is required.
190    const PARAM_IS_REQUIRED: bool = false;
191
192    /// The parameter type.
193    type ParamType;
194
195    /// The raw parameter type for validators.
196    type ParamRawType;
197
198    /// Register related types to registry.
199    fn register(registry: &mut Registry) {}
200
201    /// Returns names of security scheme if this extractor is security scheme.
202    fn security_schemes() -> Vec<&'static str> {
203        vec![]
204    }
205
206    /// Returns `true` if the extractor is a security scheme with a fallback.
207    fn has_security_fallback() -> bool {
208        false
209    }
210
211    /// Returns the location of the parameter if this extractor is parameter.
212    fn param_in() -> Option<MetaParamIn> {
213        None
214    }
215
216    /// Returns the schema of the parameter if this extractor is parameter.
217    fn param_schema_ref() -> Option<MetaSchemaRef> {
218        None
219    }
220
221    /// Returns `MetaRequest` if this extractor is request object.
222    fn request_meta() -> Option<MetaRequest> {
223        None
224    }
225
226    /// Returns a reference to the raw type of this parameter.
227    fn param_raw_type(&self) -> Option<&Self::ParamRawType> {
228        None
229    }
230
231    /// Parse from the HTTP request.
232    fn from_request(
233        request: &'a Request,
234        body: &mut RequestBody,
235        param_opts: ExtractParamOptions<Self::ParamType>,
236    ) -> impl Future<Output = Result<Self>> + Send;
237}
238
239impl<'a, T: FromRequest<'a>> ApiExtractor<'a> for T {
240    const TYPES: &'static [ApiExtractorType] = &[ApiExtractorType::PoemExtractor];
241
242    type ParamType = ();
243    type ParamRawType = ();
244
245    async fn from_request(
246        request: &'a Request,
247        body: &mut RequestBody,
248        _param_opts: ExtractParamOptions<Self::ParamType>,
249    ) -> Result<Self> {
250        // FIXME: remove the unnecessary boxed
251        // https://github.com/rust-lang/rust/issues/100013
252        T::from_request(request, body).boxed().await
253    }
254}
255
256/// Represents an OpenAPI response content object.
257pub trait ResponseContent {
258    /// Returns the media types in this content.
259    fn media_types() -> Vec<MetaMediaType>;
260
261    /// Register the schema contained in this content to the registry.
262    #[allow(unused_variables)]
263    fn register(registry: &mut Registry) {}
264}
265
266impl<T: Payload> ResponseContent for T {
267    fn media_types() -> Vec<MetaMediaType> {
268        vec![MetaMediaType {
269            content_type: T::CONTENT_TYPE,
270            schema: T::schema_ref(),
271        }]
272    }
273
274    fn register(registry: &mut Registry) {
275        T::register(registry);
276    }
277}
278
279/// Represents an OpenAPI responses object.
280///
281/// # Provided Implementations
282///
283/// - **Binary&lt;T: Type>**
284///
285///    A binary response with content type `application/octet-stream`.
286///
287/// - **Json&lt;T: Type>**
288///
289///    A JSON response with content type `application/json`.
290///
291/// - **PlainText&lt;T: Type>**
292///
293///    A utf8 string response with content type `text/plain`.
294///
295/// - **Attachment&lt;T: Type>**
296///
297///    A file download response, the content type is
298///    `application/octet-stream`.
299///
300/// - **Response&lt;T: Type>**
301///
302///    A response type use it to modify the status code and HTTP headers.
303///
304/// - **()**
305///
306///     It means that this API does not have any response body.
307///
308/// - **poem::Result&lt;T: ApiResponse>**
309///
310///     It means that an error may occur in this API.
311///
312/// - **Any type derived from the [`ApiResponse`](crate::ApiResponse) macro**
313///
314///     A complex response  derived from the `ApiResponse` macro.
315pub trait ApiResponse: Sized {
316    /// If true, it means that the response object has a custom bad request
317    /// handler.
318    const BAD_REQUEST_HANDLER: bool = false;
319
320    /// Gets metadata of this response.
321    fn meta() -> MetaResponses;
322
323    /// Register the schema contained in this response object to the registry.
324    fn register(registry: &mut Registry);
325
326    /// Convert [`poem::Error`] to this response object.
327    #[allow(unused_variables)]
328    fn from_parse_request_error(err: Error) -> Self {
329        unreachable!()
330    }
331}
332
333impl ApiResponse for () {
334    fn meta() -> MetaResponses {
335        MetaResponses {
336            responses: vec![MetaResponse {
337                description: "",
338                status: Some(200),
339                content: vec![],
340                headers: vec![],
341            }],
342        }
343    }
344
345    fn register(_registry: &mut Registry) {}
346}
347
348impl ApiResponse for Error {
349    fn meta() -> MetaResponses {
350        MetaResponses {
351            responses: Vec::new(),
352        }
353    }
354
355    fn register(_registry: &mut Registry) {}
356}
357
358impl<T, E> ApiResponse for Result<T, E>
359where
360    T: ApiResponse,
361    E: ApiResponse + Into<Error> + Send + Sync + 'static,
362{
363    const BAD_REQUEST_HANDLER: bool = T::BAD_REQUEST_HANDLER;
364
365    fn meta() -> MetaResponses {
366        let mut meta = T::meta();
367        meta.responses.extend(E::meta().responses);
368        meta
369    }
370
371    fn register(registry: &mut Registry) {
372        T::register(registry);
373        E::register(registry);
374    }
375
376    fn from_parse_request_error(err: Error) -> Self {
377        Ok(T::from_parse_request_error(err))
378    }
379}
380
381#[cfg(feature = "websocket")]
382impl<F, Fut> ApiResponse for poem::web::websocket::WebSocketUpgraded<F>
383where
384    F: FnOnce(poem::web::websocket::WebSocketStream) -> Fut + Send + Sync + 'static,
385    Fut: std::future::Future + Send + 'static,
386{
387    fn meta() -> MetaResponses {
388        MetaResponses {
389            responses: vec![MetaResponse {
390                description: "A websocket response",
391                status: Some(101),
392                content: vec![],
393                headers: vec![],
394            }],
395        }
396    }
397
398    fn register(_registry: &mut Registry) {}
399}
400
401/// Represents an OpenAPI tags.
402pub trait Tags {
403    /// Register this tag type to registry.
404    fn register(&self, registry: &mut Registry);
405
406    /// Gets the tag name.
407    fn name(&self) -> &'static str;
408}
409
410/// Represents a OAuth scopes.
411pub trait OAuthScopes {
412    /// Gets metadata of this object.
413    fn meta() -> Vec<MetaOAuthScope>;
414
415    /// Get the scope name.
416    fn name(&self) -> &'static str;
417}
418
419/// A operation id that can be obtained from the response
420#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
421pub struct OperationId(pub &'static str);
422
423impl Display for OperationId {
424    #[inline]
425    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
426        f.write_str(self.0)
427    }
428}
429
430/// Represents an OpenAPI object.
431pub trait OpenApi: Sized {
432    /// Gets metadata of this API object.
433    fn meta() -> Vec<MetaApi>;
434
435    /// Register some types to the registry.
436    fn register(registry: &mut Registry);
437
438    /// Adds all API endpoints to the routing object.
439    fn add_routes(self, route_table: &mut HashMap<String, HashMap<Method, BoxEndpoint<'static>>>);
440}
441
442macro_rules! impl_openapi_for_tuple {
443    (($head:ident, $hn:tt), $(($tail:ident, $tn:tt)),*) => {
444        impl<$head: OpenApi, $($tail: OpenApi),*> OpenApi for ($head, $($tail),*) {
445            fn meta() -> Vec<MetaApi> {
446                let mut metadata = $head::meta();
447                $(
448                metadata.extend($tail::meta());
449                )*
450                metadata
451            }
452
453            fn register(registry: &mut Registry) {
454                $head::register(registry);
455                $(
456                $tail::register(registry);
457                )*
458            }
459
460            fn add_routes(self, route_table: &mut HashMap<String, HashMap<Method, BoxEndpoint<'static>>>) {
461                self.$hn.add_routes(route_table);
462                $(
463                self.$tn.add_routes(route_table);
464                )*
465            }
466        }
467    };
468
469    () => {};
470}
471
472#[rustfmt::skip]
473impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9), (T11, 10), (T12, 11), (T13, 12), (T14, 13), (T15, 14), (T16, 15));
474#[rustfmt::skip]
475impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9), (T11, 10), (T12, 11), (T13, 12), (T14, 13), (T15, 14));
476#[rustfmt::skip]
477impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9), (T11, 10), (T12, 11), (T13, 12), (T14, 13));
478#[rustfmt::skip]
479impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9), (T11, 10), (T12, 11), (T13, 12));
480#[rustfmt::skip]
481impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9), (T11, 10), (T12, 11));
482#[rustfmt::skip]
483impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9), (T11, 10));
484#[rustfmt::skip]
485impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8), (T10, 9));
486#[rustfmt::skip]
487impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7), (T9, 8));
488#[rustfmt::skip]
489impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6), (T8, 7));
490#[rustfmt::skip]
491impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5), (T7, 6));
492#[rustfmt::skip]
493impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4), (T6, 5));
494#[rustfmt::skip]
495impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3), (T5, 4));
496#[rustfmt::skip]
497impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2), (T4, 3));
498#[rustfmt::skip]
499impl_openapi_for_tuple!((T1, 0), (T2, 1), (T3, 2));
500#[rustfmt::skip]
501impl_openapi_for_tuple!((T1, 0), (T2, 1));
502
503impl OpenApi for () {
504    fn meta() -> Vec<MetaApi> {
505        vec![]
506    }
507
508    fn register(_registry: &mut Registry) {}
509
510    fn add_routes(self, _route_table: &mut HashMap<String, HashMap<Method, BoxEndpoint<'static>>>) {
511    }
512}
513
514/// Represents a webhook object.
515pub trait Webhook: Sized {
516    /// Gets metadata of this webhooks object.
517    fn meta() -> Vec<MetaWebhook>;
518
519    /// Register some types to the registry.
520    fn register(registry: &mut Registry);
521}
522
523impl Webhook for () {
524    fn meta() -> Vec<MetaWebhook> {
525        vec![]
526    }
527
528    fn register(_: &mut Registry) {}
529}
poem_openapi/base.rs

poem_openapi/
base.rs
