utoipa/openapi/
encoding.rs

1//! Implements encoding object for content.
2
3use std::collections::BTreeMap;
4
5use serde::{Deserialize, Serialize};
6
7use super::extensions::Extensions;
8use super::{builder, path::ParameterStyle, set_value, Header};
9
10builder! {
11    EncodingBuilder;
12
13    /// A single encoding definition applied to a single schema [`Object
14    /// property`](crate::openapi::schema::Object::properties).
15    #[derive(Serialize, Deserialize, Default, Clone, PartialEq)]
16    #[cfg_attr(feature = "debug", derive(Debug))]
17    #[serde(rename_all = "camelCase")]
18    #[non_exhaustive]
19    pub struct Encoding {
20        /// The Content-Type for encoding a specific property. Default value depends on the property
21        /// type: for string with format being binary – `application/octet-stream`; for other primitive
22        /// types – `text/plain`; for object - `application/json`; for array – the default is defined
23        /// based on the inner type. The value can be a specific media type (e.g. `application/json`),
24        /// a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
25        #[serde(skip_serializing_if = "Option::is_none")]
26        pub content_type: Option<String>,
27
28        /// A map allowing additional information to be provided as headers, for example
29        /// Content-Disposition. Content-Type is described separately and SHALL be ignored in this
30        /// section. This property SHALL be ignored if the request body media type is not a multipart.
31        #[serde(skip_serializing_if = "BTreeMap::is_empty")]
32        pub headers: BTreeMap<String, Header>,
33
34        /// Describes how a specific property value will be serialized depending on its type. See
35        /// Parameter Object for details on the style property. The behavior follows the same values as
36        /// query parameters, including default values. This property SHALL be ignored if the request
37        /// body media type is not `application/x-www-form-urlencoded`.
38        #[serde(skip_serializing_if = "Option::is_none")]
39        pub style: Option<ParameterStyle>,
40
41        /// When this is true, property values of type array or object generate separate parameters for
42        /// each value of the array, or key-value-pair of the map. For other types of properties this
43        /// property has no effect. When style is form, the default value is true. For all other
44        /// styles, the default value is false. This property SHALL be ignored if the request body
45        /// media type is not `application/x-www-form-urlencoded`.
46        #[serde(skip_serializing_if = "Option::is_none")]
47        pub explode: Option<bool>,
48
49        /// Determines whether the parameter value SHOULD allow reserved characters, as defined by
50        /// RFC3986 `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is
51        /// false. This property SHALL be ignored if the request body media type is not
52        /// `application/x-www-form-urlencoded`.
53        #[serde(skip_serializing_if = "Option::is_none")]
54        pub allow_reserved: Option<bool>,
55
56        /// Optional extensions "x-something".
57        #[serde(skip_serializing_if = "Option::is_none", flatten)]
58        pub extensions: Option<Extensions>,
59    }
60}
61
62impl EncodingBuilder {
63    /// Set the content type. See [`Encoding::content_type`].
64    pub fn content_type<S: Into<String>>(mut self, content_type: Option<S>) -> Self {
65        set_value!(self content_type content_type.map(Into::into))
66    }
67
68    /// Add a [`Header`]. See [`Encoding::headers`].
69    pub fn header<S: Into<String>, H: Into<Header>>(mut self, header_name: S, header: H) -> Self {
70        self.headers.insert(header_name.into(), header.into());
71
72        self
73    }
74
75    /// Set the style [`ParameterStyle`]. See [`Encoding::style`].
76    pub fn style(mut self, style: Option<ParameterStyle>) -> Self {
77        set_value!(self style style)
78    }
79
80    /// Set the explode. See [`Encoding::explode`].
81    pub fn explode(mut self, explode: Option<bool>) -> Self {
82        set_value!(self explode explode)
83    }
84
85    /// Set the allow reserved. See [`Encoding::allow_reserved`].
86    pub fn allow_reserved(mut self, allow_reserved: Option<bool>) -> Self {
87        set_value!(self allow_reserved allow_reserved)
88    }
89
90    /// Add openapi extensions (x-something) of the API.
91    pub fn extensions(mut self, extensions: Option<Extensions>) -> Self {
92        set_value!(self extensions extensions)
93    }
94}
utoipa/openapi/encoding.rs

utoipa/openapi/
encoding.rs
