1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
//! Implements [OpenAPI Xml Object][xml_object] types.
//!
//! [xml_object]: https://spec.openapis.org/oas/latest.html#xml-object
use std::borrow::Cow;
use serde::{Deserialize, Serialize};
use super::{builder, set_value};
builder! {
/// # Examples
///
/// Create [`Xml`] with [`XmlBuilder`].
/// ```rust
/// # use utoipa::openapi::xml::XmlBuilder;
/// let xml = XmlBuilder::new()
/// .name(Some("some_name"))
/// .prefix(Some("prefix"))
/// .build();
/// ```
XmlBuilder;
/// Implements [OpenAPI Xml Object][xml_object].
///
/// Can be used to modify xml output format of specific [OpenAPI Schema Object][schema_object] which are
/// implemented in [`schema`][schema] module.
///
/// [xml_object]: https://spec.openapis.org/oas/latest.html#xml-object
/// [schema_object]: https://spec.openapis.org/oas/latest.html#schema-object
/// [schema]: ../schema/index.html
#[non_exhaustive]
#[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "debug", derive(Debug))]
#[serde(rename_all = "camelCase")]
pub struct Xml {
/// Used to replace the name of attribute or type used in schema property.
/// When used with [`Xml::wrapped`] attribute the name will be used as a wrapper name
/// for wrapped array instead of the item or type name.
#[serde(skip_serializing_if = "Option::is_none")]
pub name: Option<Cow<'static, str>>,
/// Valid uri definition of namespace used in xml.
#[serde(skip_serializing_if = "Option::is_none")]
pub namespace: Option<Cow<'static, str>>,
/// Prefix for xml element [`Xml::name`].
#[serde(skip_serializing_if = "Option::is_none")]
pub prefix: Option<Cow<'static, str>>,
/// XML node type for this schema.
#[serde(skip_serializing_if = "Option::is_none")]
pub node_type: Option<Cow<'static, str>>,
/// Flag deciding will this attribute translate to element attribute instead of xml element.
#[serde(skip_serializing_if = "Option::is_none")]
pub attribute: Option<bool>,
/// Flag only usable with array definition. If set to true the output xml will wrap the array of items
/// `<pets><pet></pet></pets>` instead of unwrapped `<pet></pet>`.
#[serde(skip_serializing_if = "Option::is_none")]
pub wrapped: Option<bool>,
}
}
impl Xml {
/// Construct a new [`Xml`] object.
pub fn new() -> Self {
Self {
..Default::default()
}
}
}
impl XmlBuilder {
/// Add [`Xml::name`] to xml object.
///
/// Builder style chainable consuming add name method.
pub fn name<S: Into<Cow<'static, str>>>(mut self, name: Option<S>) -> Self {
set_value!(self name name.map(|name| name.into()))
}
/// Add [`Xml::namespace`] to xml object.
///
/// Builder style chainable consuming add namespace method.
pub fn namespace<S: Into<Cow<'static, str>>>(mut self, namespace: Option<S>) -> Self {
set_value!(self namespace namespace.map(|namespace| namespace.into()))
}
/// Add [`Xml::prefix`] to xml object.
///
/// Builder style chainable consuming add prefix method.
pub fn prefix<S: Into<Cow<'static, str>>>(mut self, prefix: Option<S>) -> Self {
set_value!(self prefix prefix.map(|prefix| prefix.into()))
}
/// Add [`Xml::node_type`] to xml object.
///
/// Builder style chainable consuming add node type method.
pub fn node_type<S: Into<Cow<'static, str>>>(mut self, node_type: Option<S>) -> Self {
set_value!(self node_type node_type.map(|node_type| node_type.into()))
}
/// Mark [`Xml`] object as attribute. See [`Xml::attribute`].
///
/// Builder style chainable consuming add attribute method.
pub fn attribute(mut self, attribute: Option<bool>) -> Self {
set_value!(self attribute attribute)
}
/// Mark [`Xml`] object wrapped. See [`Xml::wrapped`].
///
/// Builder style chainable consuming add wrapped method.
pub fn wrapped(mut self, wrapped: Option<bool>) -> Self {
set_value!(self wrapped wrapped)
}
}
#[cfg(test)]
mod tests {
use super::Xml;
#[test]
fn xml_new() {
let xml = Xml::new();
assert!(xml.name.is_none());
assert!(xml.namespace.is_none());
assert!(xml.prefix.is_none());
assert!(xml.attribute.is_none());
assert!(xml.wrapped.is_none());
}
}