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/// Describes a single operation parameter.
64#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
65#[serde(tag = "in", rename_all = "camelCase")]
66pub enum Parameter {
67    /// Parameters that are appended to the URL. For example, in /items?id=###,
68    /// the query parameter is id.
69    #[serde(rename_all = "camelCase")]
70    Query {
71        #[serde(flatten)]
72        parameter_data: ParameterData,
73        /// Determines whether the parameter value SHOULD allow reserved
74        /// characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included
75        /// without percent-encoding. This property only applies to parameters
76        /// with an in value of query. The default value is false.
77        #[serde(default, skip_serializing_if = "is_false")]
78        allow_reserved: bool,
79        /// Describes how the parameter value will be serialized depending on
80        /// the type of the parameter value. Default values (based on value of
81        /// in): for query - form; for path - simple; for header - simple; for
82        /// cookie - form.
83        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
84        style: QueryStyle,
85        /// Sets the ability to pass empty-valued parameters. This is
86        /// valid only for query parameters and allows sending a parameter
87        /// with an empty value. Default value is false. If style is used,
88        /// and if behavior is n/a (cannot be serialized), the value of
89        /// allowEmptyValue SHALL be ignored.
90        #[serde(skip_serializing_if = "Option::is_none")]
91        allow_empty_value: Option<bool>,
92    },
93    /// Custom headers that are expected as part of the request. Note that
94    /// RFC7230 states header names are case insensitive.
95    Header {
96        #[serde(flatten)]
97        parameter_data: ParameterData,
98        /// Describes how the parameter value will be serialized depending on
99        /// the type of the parameter value. Default values (based on value of
100        /// in): for query - form; for path - simple; for header - simple; for
101        /// cookie - form.
102        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
103        style: HeaderStyle,
104    },
105    /// Used together with Path Templating, where the parameter value is
106    /// actually part of the operation's URL. This does not include the host or
107    /// base path of the API. For example, in /items/{itemId}, the path
108    /// parameter is itemId.
109    Path {
110        #[serde(flatten)]
111        parameter_data: ParameterData,
112        /// Describes how the parameter value will be serialized depending on
113        /// the type of the parameter value. Default values (based on value of
114        /// in): for query - form; for path - simple; for header - simple; for
115        /// cookie - form.
116        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
117        style: PathStyle,
118    },
119    /// Used to pass a specific cookie value to the API.
120    Cookie {
121        #[serde(flatten)]
122        parameter_data: ParameterData,
123        /// Describes how the parameter value will be serialized depending on
124        /// the type of the parameter value. Default values (based on value of
125        /// in): for query - form; for path - simple; for header - simple; for
126        /// cookie - form.
127        #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")]
128        style: CookieStyle,
129    },
130}
131
132impl Parameter {
133    /// Returns the `parameter_data` field of this [ParameterData].
134    pub fn parameter_data(self) -> ParameterData {
135        match self {
136            Parameter::Query {
137                parameter_data,
138                allow_reserved: _,
139                style: _,
140                allow_empty_value: _,
141            } => parameter_data,
142            Parameter::Header {
143                parameter_data,
144                style: _,
145            } => parameter_data,
146            Parameter::Path {
147                parameter_data,
148                style: _,
149            } => parameter_data,
150            Parameter::Cookie {
151                parameter_data,
152                style: _,
153            } => parameter_data,
154        }
155    }
156
157    /// Returns the `parameter_data` field of this [ParameterData] by reference.
158    pub fn parameter_data_ref(&self) -> &ParameterData {
159        match self {
160            Parameter::Query {
161                parameter_data,
162                allow_reserved: _,
163                style: _,
164                allow_empty_value: _,
165            } => parameter_data,
166            Parameter::Header {
167                parameter_data,
168                style: _,
169            } => parameter_data,
170            Parameter::Path {
171                parameter_data,
172                style: _,
173            } => parameter_data,
174            Parameter::Cookie {
175                parameter_data,
176                style: _,
177            } => parameter_data,
178        }
179    }
180}
181
182struct SkipSerializeIfDefault;
183impl SkipSerializeIfDefault {
184    #[cfg(feature = "skip_serializing_defaults")]
185    fn skip<D: Default + std::cmp::PartialEq>(value: &D) -> bool {
186        value == &Default::default()
187    }
188    #[cfg(not(feature = "skip_serializing_defaults"))]
189    fn skip<D: Default + std::cmp::PartialEq>(_value: &D) -> bool {
190        false
191    }
192}
193
194#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
195#[serde(rename_all = "camelCase")]
196pub enum PathStyle {
197    /// Path-style parameters defined by RFC6570.
198    Matrix,
199    /// Label style parameters defined by RFC6570.
200    Label,
201    /// Simple style parameters defined by RFC6570.
202    Simple,
203}
204
205impl Default for PathStyle {
206    fn default() -> Self {
207        PathStyle::Simple
208    }
209}
210#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
211#[serde(rename_all = "camelCase")]
212pub enum QueryStyle {
213    /// Form style parameters defined by RFC6570.
214    Form,
215    /// Space separated array values.
216    SpaceDelimited,
217    /// Pipe separated array values.
218    PipeDelimited,
219    /// Provides a simple way of rendering nested objects using form parameters.
220    DeepObject,
221}
222
223impl Default for QueryStyle {
224    fn default() -> Self {
225        QueryStyle::Form
226    }
227}
228#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
229#[serde(rename_all = "camelCase")]
230pub enum CookieStyle {
231    /// Form style parameters defined by RFC6570.
232    Form,
233}
234
235impl Default for CookieStyle {
236    fn default() -> CookieStyle {
237        CookieStyle::Form
238    }
239}
240#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
241#[serde(rename_all = "camelCase")]
242pub enum HeaderStyle {
243    /// Simple style parameters defined by RFC6570.
244    Simple,
245}
246
247impl Default for HeaderStyle {
248    fn default() -> HeaderStyle {
249        HeaderStyle::Simple
250    }
251}
openapiv3/parameter.rs

openapiv3/
parameter.rs
