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, Ref, RefOr};
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, RefOr<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 /// Encoding information for nested object properties.
57 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
58 pub encoding: BTreeMap<String, Encoding>,
59
60 /// Encoding information for tuple-like nested array items.
61 #[serde(skip_serializing_if = "Vec::is_empty", default)]
62 pub prefix_encoding: Vec<Encoding>,
63
64 /// Encoding information for each nested array item.
65 #[serde(skip_serializing_if = "Option::is_none")]
66 pub item_encoding: Option<Box<Encoding>>,
67
68 /// Optional extensions "x-something".
69 #[serde(skip_serializing_if = "Option::is_none", flatten)]
70 pub extensions: Option<Extensions>,
71 }
72}
73
74impl EncodingBuilder {
75 /// Set the content type. See [`Encoding::content_type`].
76 pub fn content_type<S: Into<String>>(mut self, content_type: Option<S>) -> Self {
77 set_value!(self content_type content_type.map(Into::into))
78 }
79
80 /// Add a [`Header`]. See [`Encoding::headers`].
81 pub fn header<S: Into<String>, H: Into<Header>>(mut self, header_name: S, header: H) -> Self {
82 self.headers
83 .insert(header_name.into(), header.into().into());
84
85 self
86 }
87
88 /// Add a [`Header`] reference. See [`Encoding::headers`].
89 pub fn header_ref<S: Into<String>>(mut self, header_name: S, header: Ref) -> Self {
90 self.headers.insert(header_name.into(), RefOr::Ref(header));
91
92 self
93 }
94
95 /// Set the style [`ParameterStyle`]. See [`Encoding::style`].
96 pub fn style(mut self, style: Option<ParameterStyle>) -> Self {
97 set_value!(self style style)
98 }
99
100 /// Set the explode. See [`Encoding::explode`].
101 pub fn explode(mut self, explode: Option<bool>) -> Self {
102 set_value!(self explode explode)
103 }
104
105 /// Set the allow reserved. See [`Encoding::allow_reserved`].
106 pub fn allow_reserved(mut self, allow_reserved: Option<bool>) -> Self {
107 set_value!(self allow_reserved allow_reserved)
108 }
109
110 /// Add nested encoding information for an object property.
111 pub fn encoding<S: Into<String>, E: Into<Encoding>>(
112 mut self,
113 property_name: S,
114 encoding: E,
115 ) -> Self {
116 self.encoding.insert(property_name.into(), encoding.into());
117 self
118 }
119
120 /// Add nested encoding information for tuple-like array items.
121 pub fn prefix_encoding<I: IntoIterator<Item = E>, E: Into<Encoding>>(
122 mut self,
123 prefix_encoding: I,
124 ) -> Self {
125 set_value!(self prefix_encoding prefix_encoding.into_iter().map(Into::into).collect())
126 }
127
128 /// Add nested encoding information for each array item.
129 pub fn item_encoding<E: Into<Encoding>>(mut self, item_encoding: Option<E>) -> Self {
130 set_value!(self item_encoding item_encoding.map(|encoding| Box::new(encoding.into())))
131 }
132
133 /// Add openapi extensions (x-something) of the API.
134 pub fn extensions(mut self, extensions: Option<Extensions>) -> Self {
135 set_value!(self extensions extensions)
136 }
137}