utoipa/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
9use super::{builder, set_value, RefOr};
10
11builder! {
12    /// # Examples
13    ///
14    /// _**Construct a new [`Example`] via builder**_
15    /// ```rust
16    /// # use utoipa::openapi::example::ExampleBuilder;
17    /// let example = ExampleBuilder::new()
18    ///     .summary("Example string response")
19    ///     .value(Some(serde_json::json!("Example value")))
20    ///     .build();
21    /// ```
22    ExampleBuilder;
23
24    /// Implements [OpenAPI Example Object][example].
25    ///
26    /// Example is used on path operations to describe possible response bodies.
27    ///
28    /// [example]: https://spec.openapis.org/oas/latest.html#example-object
29    #[non_exhaustive]
30    #[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq)]
31    #[cfg_attr(feature = "debug", derive(Debug))]
32    #[serde(rename_all = "camelCase")]
33    pub struct Example {
34        /// Short description for the [`Example`].
35        #[serde(skip_serializing_if = "String::is_empty", default)]
36        pub summary: String,
37
38        /// Long description for the [`Example`]. Value supports markdown syntax for rich text
39        /// representation.
40        #[serde(skip_serializing_if = "String::is_empty", default)]
41        pub description: String,
42
43        /// Embedded literal example value. [`Example::value`] and [`Example::external_value`] are
44        /// mutually exclusive.
45        #[serde(skip_serializing_if = "Option::is_none")]
46        pub value: Option<serde_json::Value>,
47
48        /// Embedded example value in the same form as data validated by a schema.
49        #[serde(skip_serializing_if = "Option::is_none")]
50        pub data_value: Option<serde_json::Value>,
51
52        /// String representation of the example value after serialization.
53        #[serde(skip_serializing_if = "Option::is_none")]
54        pub serialized_value: Option<String>,
55
56        /// An URI that points to a literal example value. [`Example::external_value`] provides the
57        /// capability to references an example that cannot be easily included in JSON or YAML.
58        /// [`Example::value`] and [`Example::external_value`] are mutually exclusive.
59        #[serde(skip_serializing_if = "String::is_empty", default)]
60        pub external_value: String,
61    }
62}
63
64impl Example {
65    /// Construct a new empty [`Example`]. This is effectively same as calling
66    /// [`Example::default`].
67    pub fn new() -> Self {
68        Self::default()
69    }
70}
71
72impl ExampleBuilder {
73    /// Add or change a short description for the [`Example`]. Setting this to empty `String`
74    /// will make it not render in the generated OpenAPI document.
75    pub fn summary<S: Into<String>>(mut self, summary: S) -> Self {
76        set_value!(self summary summary.into())
77    }
78
79    /// Add or change a long description for the [`Example`]. Markdown syntax is supported for rich
80    /// text representation.
81    ///
82    /// Setting this to empty `String` will make it not render in the generated
83    /// OpenAPI document.
84    pub fn description<D: Into<String>>(mut self, description: D) -> Self {
85        set_value!(self description description.into())
86    }
87
88    /// Add or change embedded literal example value. [`Example::value`] and [`Example::external_value`]
89    /// are mutually exclusive.
90    pub fn value(mut self, value: Option<serde_json::Value>) -> Self {
91        set_value!(self value value)
92    }
93
94    /// Add or change embedded data value for the [`Example`].
95    pub fn data_value(mut self, data_value: Option<serde_json::Value>) -> Self {
96        set_value!(self data_value data_value)
97    }
98
99    /// Add or change serialized value for the [`Example`].
100    pub fn serialized_value<S: Into<String>>(mut self, serialized_value: Option<S>) -> Self {
101        set_value!(
102            self
103            serialized_value
104            serialized_value.map(|serialized_value| serialized_value.into())
105        )
106    }
107
108    /// Add or change an URI that points to a literal example value. [`Example::external_value`]
109    /// provides the capability to references an example that cannot be easily included
110    /// in JSON or YAML. [`Example::value`] and [`Example::external_value`] are mutually exclusive.
111    ///
112    /// Setting this to an empty String will make the field not to render in the generated OpenAPI
113    /// document.
114    pub fn external_value<E: Into<String>>(mut self, external_value: E) -> Self {
115        set_value!(self external_value external_value.into())
116    }
117}
118
119impl From<ExampleBuilder> for RefOr<Example> {
120    fn from(example_builder: ExampleBuilder) -> Self {
121        Self::T(example_builder.build())
122    }
123}
utoipa/openapi/example.rs

utoipa/openapi/
example.rs
