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    pub fn new() -> Self {
42        Self::default()
43    }
44    /// Add or change a short description for the [`Example`]. Setting this to empty `String`
45    /// will make it not render in the generated OpenAPI document.
46    pub fn summary<S: Into<String>>(mut self, summary: S) -> Self {
47        self.summary = summary.into();
48        self
49    }
50
51    /// Add or change a long description for the [`Example`]. Markdown syntax is supported for rich
52    /// text representation.
53    ///
54    /// Setting this to empty `String` will make it not render in the generated
55    /// OpenAPI document.
56    pub fn description<D: Into<String>>(mut self, description: D) -> Self {
57        self.description = description.into();
58        self
59    }
60
61    /// Add or change embedded literal example value. [`Example::value`] and [`Example::external_value`]
62    /// are mutually exclusive.
63    pub fn value(mut self, value: serde_json::Value) -> Self {
64        self.value = Some(value);
65        self
66    }
67
68    /// Add or change an URI that points to a literal example value. [`Example::external_value`]
69    /// provides the capability to references an example that cannot be easily included
70    /// in JSON or YAML. [`Example::value`] and [`Example::external_value`] are mutually exclusive.
71    ///
72    /// Setting this to an empty String will make the field not to render in the generated OpenAPI
73    /// document.
74    pub fn external_value<E: Into<String>>(mut self, external_value: E) -> Self {
75        self.external_value = external_value.into();
76        self
77    }
78}
79
80#[cfg(test)]
81mod tests {
82    use super::*;
83
84    #[test]
85    fn test_example() {
86        let example = Example::new();
87        assert!(example.summary.is_empty());
88        assert!(example.description.is_empty());
89        assert!(example.value.is_none());
90        assert!(example.external_value.is_empty());
91
92        let example = example.summary("summary");
93        assert!(example.summary == "summary");
94
95        let example = example.description("description");
96        assert!(example.description == "description");
97
98        let example = example.external_value("external_value");
99        assert!(example.external_value == "external_value");
100
101        let example = example.value(serde_json::Value::String("value".to_string()));
102        assert!(example.value.is_some());
103        assert!(example.value.unwrap() == serde_json::Value::String("value".to_string()));
104    }
105}
salvo_oapi/openapi/example.rs

salvo_oapi/openapi/
example.rs
