salvo_oapi/openapi/
example.rs

1//! Implements [OpenAPI Example Object][example] can be used to define examples for [`Response`][response]s and
2//! [`RequestBody`][request_body]s.
3//!
4//! [example]: https://spec.openapis.org/oas/latest.html#example-object
5//! [response]: response/struct.Response.html
6//! [request_body]: request_body/struct.RequestBody.html
7use serde::{Deserialize, Serialize};
8
9/// Implements [OpenAPI Example Object][example].
10///
11/// Example is used on path operations to describe possible response bodies.
12///
13/// [example]: https://spec.openapis.org/oas/latest.html#example-object
14#[non_exhaustive]
15#[derive(Serialize, Deserialize, Default, Clone, Debug, PartialEq, Eq)]
16#[serde(rename_all = "camelCase")]
17pub struct Example {
18    /// Short description for the [`Example`].
19    #[serde(skip_serializing_if = "String::is_empty")]
20    pub summary: String,
21
22    /// Long description for the [`Example`]. Value supports markdown syntax for rich text
23    /// representation.
24    #[serde(skip_serializing_if = "String::is_empty")]
25    pub description: String,
26
27    /// Embedded literal example value. [`Example::value`] and [`Example::external_value`] are
28    /// mutually exclusive.
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub value: Option<serde_json::Value>,
31
32    /// An URI that points to a literal example value. [`Example::external_value`] provides the
33    /// capability to references an example that cannot be easily included in JSON or YAML.
34    /// [`Example::value`] and [`Example::external_value`] are mutually exclusive.
35    #[serde(skip_serializing_if = "String::is_empty")]
36    pub external_value: String,
37}
38
39impl Example {
40    /// Construct a new empty [`Example`]. This is effectively same as calling [`Example::default`].
41    #[must_use]
42    pub fn new() -> Self {
43        Self::default()
44    }
45    /// Add or change a short description for the [`Example`]. Setting this to empty `String`
46    /// will make it not render in the generated OpenAPI document.
47    #[must_use]
48    pub fn summary<S: Into<String>>(mut self, summary: S) -> Self {
49        self.summary = summary.into();
50        self
51    }
52
53    /// Add or change a long description for the [`Example`]. Markdown syntax is supported for rich
54    /// text representation.
55    ///
56    /// Setting this to empty `String` will make it not render in the generated
57    /// OpenAPI document.
58    #[must_use]
59    pub fn description<D: Into<String>>(mut self, description: D) -> Self {
60        self.description = description.into();
61        self
62    }
63
64    /// Add or change embedded literal example value. [`Example::value`] and [`Example::external_value`]
65    /// are mutually exclusive.
66    #[must_use]
67    pub fn value(mut self, value: serde_json::Value) -> Self {
68        self.value = Some(value);
69        self
70    }
71
72    /// Add or change an URI that points to a literal example value. [`Example::external_value`]
73    /// provides the capability to references an example that cannot be easily included
74    /// in JSON or YAML. [`Example::value`] and [`Example::external_value`] are mutually exclusive.
75    ///
76    /// Setting this to an empty String will make the field not to render in the generated OpenAPI
77    /// document.
78    #[must_use]
79    pub fn external_value<E: Into<String>>(mut self, external_value: E) -> Self {
80        self.external_value = external_value.into();
81        self
82    }
83}
84
85#[cfg(test)]
86mod tests {
87    use super::*;
88
89    #[test]
90    fn test_example() {
91        let example = Example::new();
92        assert!(example.summary.is_empty());
93        assert!(example.description.is_empty());
94        assert!(example.value.is_none());
95        assert!(example.external_value.is_empty());
96
97        let example = example.summary("summary");
98        assert!(example.summary == "summary");
99
100        let example = example.description("description");
101        assert!(example.description == "description");
102
103        let example = example.external_value("external_value");
104        assert!(example.external_value == "external_value");
105
106        let example = example.value(serde_json::Value::String("value".to_owned()));
107        assert!(example.value.is_some());
108        assert!(example.value.unwrap() == serde_json::Value::String("value".to_owned()));
109    }
110}
salvo_oapi/openapi/example.rs

salvo_oapi/openapi/
example.rs
