salvo_oapi/openapi/schema/
one_of.rs

1use serde::{Deserialize, Serialize};
2use serde_json::Value;
3
4use crate::{Array, Discriminator, PropMap, RefOr, Schema, SchemaType};
5
6/// OneOf [Composite Object][oneof] component holds
7/// multiple components together where API endpoint could return any of them.
8///
9/// See [`Schema::OneOf`] for more details.
10///
11/// [oneof]: https://spec.openapis.org/oas/latest.html#components-object
12#[non_exhaustive]
13#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
14pub struct OneOf {
15    /// Components of _OneOf_ component.
16    #[serde(rename = "oneOf")]
17    pub items: Vec<RefOr<Schema>>,
18
19    /// Type of [`OneOf`] e.g. `SchemaType::basic(BasicType::Object)` for `object`.
20    ///
21    /// By default this is [`SchemaType::AnyValue`] as the type is defined by items
22    /// themselves.
23    #[serde(
24        rename = "type",
25        default = "SchemaType::any",
26        skip_serializing_if = "SchemaType::is_any_value"
27    )]
28    pub schema_type: SchemaType,
29
30    /// Changes the [`OneOf`] title.
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub title: Option<String>,
33
34    /// Description of the [`OneOf`]. Markdown syntax is supported.
35    #[serde(skip_serializing_if = "Option::is_none")]
36    pub description: Option<String>,
37
38    /// Default value which is provided when user has not provided the input in Swagger UI.
39    #[serde(rename = "default", skip_serializing_if = "Option::is_none")]
40    pub default_value: Option<Value>,
41
42    /// Examples shown in UI of the value for richer documentation.
43    #[serde(skip_serializing_if = "Vec::is_empty", default)]
44    pub examples: Vec<Value>,
45
46    /// Optional discriminator field can be used to aid deserialization, serialization and
47    /// validation of a specific schema.
48    #[serde(skip_serializing_if = "Option::is_none")]
49    pub discriminator: Option<Discriminator>,
50
51    /// Optional extensions `x-something`.
52    #[serde(skip_serializing_if = "PropMap::is_empty", flatten)]
53    pub extensions: PropMap<String, serde_json::Value>,
54}
55
56impl Default for OneOf {
57    fn default() -> Self {
58        Self {
59            items: Default::default(),
60            schema_type: SchemaType::AnyValue,
61            title: Default::default(),
62            description: Default::default(),
63            default_value: Default::default(),
64            examples: Default::default(),
65            discriminator: Default::default(),
66            extensions: Default::default(),
67        }
68    }
69}
70
71impl OneOf {
72    /// Construct a new empty [`OneOf`]. This is effectively same as calling [`OneOf::default`].
73    #[must_use]
74    pub fn new() -> Self {
75        Default::default()
76    }
77
78    /// Construct a new [`OneOf`] component with given capacity.
79    ///
80    /// OneOf component is then able to contain number of components without
81    /// reallocating.
82    ///
83    /// # Examples
84    ///
85    /// Create [`OneOf`] component with initial capacity of 5.
86    /// ```
87    /// # use salvo_oapi::schema::OneOf;
88    /// let one_of = OneOf::with_capacity(5);
89    /// ```
90    #[must_use]
91    pub fn with_capacity(capacity: usize) -> Self {
92        Self {
93            items: Vec::with_capacity(capacity),
94            ..Default::default()
95        }
96    }
97    /// Adds a given [`Schema`] to [`OneOf`] [Composite Object][composite]
98    ///
99    /// [composite]: https://spec.openapis.org/oas/latest.html#components-object
100    #[must_use]
101    pub fn item<I: Into<RefOr<Schema>>>(mut self, component: I) -> Self {
102        self.items.push(component.into());
103
104        self
105    }
106
107    /// Add or change type of the object e.g. to change type to _`string`_
108    /// use value `SchemaType::Type(Type::String)`.
109    #[must_use]
110    pub fn schema_type<T: Into<SchemaType>>(mut self, schema_type: T) -> Self {
111        self.schema_type = schema_type.into();
112        self
113    }
114
115    /// Add or change the title of the [`OneOf`].
116    #[must_use]
117    pub fn title(mut self, title: impl Into<String>) -> Self {
118        self.title = Some(title.into());
119        self
120    }
121
122    /// Add or change optional description for `OneOf` component.
123    #[must_use]
124    pub fn description(mut self, description: impl Into<String>) -> Self {
125        self.description = Some(description.into());
126        self
127    }
128
129    /// Add or change default value for the object which is provided when user has not provided the
130    /// input in Swagger UI.
131    #[must_use]
132    pub fn default_value(mut self, default: Value) -> Self {
133        self.default_value = Some(default);
134        self
135    }
136
137    /// Add an example shown in UI of the value for richer documentation.
138    #[must_use]
139    pub fn example<V: Into<Value>>(mut self, example: V) -> Self {
140        self.examples.push(example.into());
141        self
142    }
143
144    /// Set examples shown in UI of the value for richer documentation.
145    #[must_use]
146    pub fn examples<I: IntoIterator<Item = V>, V: Into<Value>>(mut self, examples: I) -> Self {
147        self.examples = examples.into_iter().map(Into::into).collect();
148        self
149    }
150
151    /// Add an example shown in UI of the value for richer documentation.
152    #[deprecated = "Use `example` instead"]
153    #[must_use]
154    pub fn add_example<V: Into<Value>>(mut self, example: V) -> Self {
155        self.examples.push(example.into());
156        self
157    }
158
159    /// Add or change discriminator field of the composite [`OneOf`] type.
160    #[must_use]
161    pub fn discriminator(mut self, discriminator: Discriminator) -> Self {
162        self.discriminator = Some(discriminator);
163        self
164    }
165
166    /// Add openapi extension (`x-something`) for [`OneOf`].
167    #[must_use]
168    pub fn add_extension<K: Into<String>>(mut self, key: K, value: serde_json::Value) -> Self {
169        self.extensions.insert(key.into(), value);
170        self
171    }
172
173    /// Convert type to [`Array`].
174    #[must_use]
175    pub fn to_array(self) -> Array {
176        Array::new().items(self)
177    }
178}
179
180impl From<OneOf> for Schema {
181    fn from(one_of: OneOf) -> Self {
182        Self::OneOf(one_of)
183    }
184}
185
186impl From<OneOf> for RefOr<Schema> {
187    fn from(one_of: OneOf) -> Self {
188        Self::Type(Schema::OneOf(one_of))
189    }
190}
191
192#[cfg(test)]
193mod tests {
194    use assert_json_diff::assert_json_eq;
195    use serde_json::json;
196
197    use super::*;
198
199    #[test]
200    fn test_build_one_of() {
201        let one_of = OneOf::with_capacity(5)
202            .title("title")
203            .description("description")
204            .default_value(Value::String("default".to_owned()))
205            .example(Value::String("example1".to_owned()))
206            .example(Value::String("example2".to_owned()))
207            .discriminator(Discriminator::new("discriminator".to_owned()));
208
209        assert_eq!(one_of.items.len(), 0);
210        assert_eq!(one_of.items.capacity(), 5);
211        assert_json_eq!(
212            one_of,
213            json!({
214                "oneOf": [],
215                "title": "title",
216                "description": "description",
217                "default": "default",
218                "examples": ["example1", "example2"],
219                "discriminator": {
220                    "propertyName": "discriminator"
221                }
222            })
223        )
224    }
225
226    #[test]
227    fn test_schema_from_one_of() {
228        let one_of = OneOf::new();
229        let schema = Schema::from(one_of);
230        assert_json_eq!(
231            schema,
232            json!({
233                "oneOf": []
234            })
235        )
236    }
237
238    #[test]
239    fn test_refor_schema_from_one_of() {
240        let one_of = OneOf::new();
241        let ref_or: RefOr<Schema> = RefOr::from(one_of);
242        assert_json_eq!(
243            ref_or,
244            json!({
245                "oneOf": []
246            })
247        )
248    }
249
250    #[test]
251    fn test_oneof_with_extensions() {
252        let expected = json!("value");
253        let json_value = OneOf::new().add_extension("x-some-extension", expected.clone());
254
255        let value = serde_json::to_value(&json_value).unwrap();
256        assert_eq!(value.get("x-some-extension"), Some(&expected));
257    }
258}
salvo_oapi/openapi/schema/one_of.rs

salvo_oapi/openapi/schema/
one_of.rs
