openapiv3/
parameter.rs

1use crate::*;
2use indexmap::IndexMap;
3use serde::{Deserialize, Serialize};
4
5/// Describes a single operation parameter.
6///
7/// A unique parameter is defined by a combination of a name and location.
8#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
9pub struct ParameterData {
10    /// REQUIRED. The name of the parameter. Parameter names are case sensitive.
11    /// If in is "path", the name field MUST correspond to the associated path
12    /// segment from the path field in the Paths Object. See Path Templating for
13    /// further information.
14    ///
15    /// If in is "header" and the name field is "Accept", "Content-Type" or
16    /// "Authorization", the parameter definition SHALL be ignored.
17    ///
18    /// For all other cases, the name corresponds to the parameter name
19    /// used by the in property.
20    pub name: String,
21    /// A brief description of the parameter. This could
22    /// contain examples of use. CommonMark syntax MAY be
23    /// used for rich text representation.
24    #[serde(skip_serializing_if = "Option::is_none")]
25    pub description: Option<String>,
26    /// Determines whether this parameter is mandatory.
27    /// If the parameter location is "path", this property
28    /// is REQUIRED and its value MUST be true. Otherwise,
29    /// the property MAY be included and its default value
30    /// is false.
31    #[serde(default, skip_serializing_if = "is_false")]
32    pub required: bool,
33    /// Specifies that a parameter is deprecated and SHOULD
34    /// be transitioned out of usage.
35    #[serde(skip_serializing_if = "Option::is_none")]
36    pub deprecated: Option<bool>,
37    #[serde(flatten)]
38    pub format: ParameterSchemaOrContent,
39    #[serde(skip_serializing_if = "Option::is_none")]
40    pub example: Option<serde_json::Value>,
41    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
42    pub examples: IndexMap<String, ReferenceOr<Example>>,
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub explode: Option<bool>,
45    /// Inline extensions to this object.
46    #[serde(flatten, deserialize_with = "crate::util::deserialize_extensions")]
47    pub extensions: IndexMap<String, serde_json::Value>,
48}
49
50#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
51#[serde(rename_all = "camelCase")]
52pub enum ParameterSchemaOrContent {
53    /// The schema defining the type used for the parameter.
54    Schema(ReferenceOr<Schema>),
55    /// A map containing the representations for the parameter. The key is the
56    /// media type and the value describes it. The map MUST only contain one
57    /// entry.
58    Content(Content),
59}
60
61pub type Content = IndexMap<String, MediaType>;
62
63#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
64#[serde(tag = "in", rename_all = "camelCase")]
65pub enum Parameter {
66    #[serde(rename_all = "camelCase")]
67    Query {
68        #[serde(flatten)]
69        parameter_data: ParameterData,
70        /// Determines whether the parameter value SHOULD allow reserved
71        /// characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included
72        /// without percent-encoding. This property only applies to parameters
73        /// with an in value of query. The default value is false.
74        #[serde(default, skip_serializing_if = "is_false")]
75        allow_reserved: bool,
76        /// Describes how the parameter value will be serialized depending on
77        /// the type of the parameter value. Default values (based on value of
78        /// in): for query - form; for path - simple; for header - simple; for
79        /// cookie - form.
80        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
81        style: QueryStyle,
82        /// Sets the ability to pass empty-valued parameters. This is
83        /// valid only for query parameters and allows sending a parameter
84        /// with an empty value. Default value is false. If style is used,
85        /// and if behavior is n/a (cannot be serialized), the value of
86        /// allowEmptyValue SHALL be ignored.
87        #[serde(skip_serializing_if = "Option::is_none")]
88        allow_empty_value: Option<bool>,
89    },
90    Header {
91        #[serde(flatten)]
92        parameter_data: ParameterData,
93        /// Describes how the parameter value will be serialized depending on
94        /// the type of the parameter value. Default values (based on value of
95        /// in): for query - form; for path - simple; for header - simple; for
96        /// cookie - form.
97        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
98        style: HeaderStyle,
99    },
100    Path {
101        #[serde(flatten)]
102        parameter_data: ParameterData,
103        /// Describes how the parameter value will be serialized depending on
104        /// the type of the parameter value. Default values (based on value of
105        /// in): for query - form; for path - simple; for header - simple; for
106        /// cookie - form.
107        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
108        style: PathStyle,
109    },
110    Cookie {
111        #[serde(flatten)]
112        parameter_data: ParameterData,
113        /// Describes how the parameter value will be serialized depending on
114        /// the type of the parameter value. Default values (based on value of
115        /// in): for query - form; for path - simple; for header - simple; for
116        /// cookie - form.
117        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
118        style: CookieStyle,
119    },
120}
121
122impl Parameter {
123    /// Returns the `parameter_data` field of this [ParameterData].
124    pub fn parameter_data(self) -> ParameterData {
125        match self {
126            Parameter::Query {
127                parameter_data,
128                allow_reserved: _,
129                style: _,
130                allow_empty_value: _,
131            } => parameter_data,
132            Parameter::Header {
133                parameter_data,
134                style: _,
135            } => parameter_data,
136            Parameter::Path {
137                parameter_data,
138                style: _,
139            } => parameter_data,
140            Parameter::Cookie {
141                parameter_data,
142                style: _,
143            } => parameter_data,
144        }
145    }
146
147    /// Returns the `parameter_data` field of this [ParameterData] by reference.
148    pub fn parameter_data_ref(&self) -> &ParameterData {
149        match self {
150            Parameter::Query {
151                parameter_data,
152                allow_reserved: _,
153                style: _,
154                allow_empty_value: _,
155            } => parameter_data,
156            Parameter::Header {
157                parameter_data,
158                style: _,
159            } => parameter_data,
160            Parameter::Path {
161                parameter_data,
162                style: _,
163            } => parameter_data,
164            Parameter::Cookie {
165                parameter_data,
166                style: _,
167            } => parameter_data,
168        }
169    }
170}
171
172struct SkipSerializeIfDefault;
173impl SkipSerializeIfDefault {
174    #[cfg(feature = "skip_serializing_defaults")]
175    fn skip<D: Default + std::cmp::PartialEq>(value: &D) -> bool {
176        value == &Default::default()
177    }
178    #[cfg(not(feature = "skip_serializing_defaults"))]
179    fn skip<D: Default + std::cmp::PartialEq>(_value: &D) -> bool {
180        false
181    }
182}
183
184#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
185#[serde(rename_all = "camelCase")]
186pub enum PathStyle {
187    Matrix,
188    Label,
189    Simple,
190}
191
192impl Default for PathStyle {
193    fn default() -> Self {
194        PathStyle::Simple
195    }
196}
197#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
198#[serde(rename_all = "camelCase")]
199pub enum QueryStyle {
200    Form,
201    SpaceDelimited,
202    PipeDelimited,
203    DeepObject,
204}
205
206impl Default for QueryStyle {
207    fn default() -> Self {
208        QueryStyle::Form
209    }
210}
211#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
212#[serde(rename_all = "camelCase")]
213pub enum CookieStyle {
214    Form,
215}
216
217impl Default for CookieStyle {
218    fn default() -> CookieStyle {
219        CookieStyle::Form
220    }
221}
222#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
223#[serde(rename_all = "camelCase")]
224pub enum HeaderStyle {
225    Simple,
226}
227
228impl Default for HeaderStyle {
229    fn default() -> HeaderStyle {
230        HeaderStyle::Simple
231    }
232}
openapiv3/parameter.rs

openapiv3/
parameter.rs
