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

//! Implements [OpenAPI Example Object][example] can be used to define examples for [`Response`][response]s and
//! [`RequestBody`][request_body]s.
//!
//! [example]: https://spec.openapis.org/oas/latest.html#example-object
//! [response]: response/struct.Response.html
//! [request_body]: request_body/struct.RequestBody.html
use serde::{Deserialize, Serialize};

use super::{builder, set_value, RefOr};

builder! {
    /// # Examples
    ///
    /// _**Construct a new [`Example`] via builder**_
    /// ```rust
    /// # use utoipa::openapi::example::ExampleBuilder;
    /// let example = ExampleBuilder::new()
    ///     .summary("Example string response")
    ///     .value(Some(serde_json::json!("Example value")))
    ///     .build();
    /// ```
    ExampleBuilder;

    /// Implements [OpenAPI Example Object][example].
    ///
    /// Example is used on path operations to describe possible response bodies.
    ///
    /// [example]: https://spec.openapis.org/oas/latest.html#example-object
    #[non_exhaustive]
    #[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq)]
    #[cfg_attr(feature = "debug", derive(Debug))]
    #[serde(rename_all = "camelCase")]
    pub struct Example {
        /// Short description for the [`Example`].
        #[serde(skip_serializing_if = "String::is_empty")]
        pub summary: String,

        /// Long description for the [`Example`]. Value supports markdown syntax for rich text
        /// representation.
        #[serde(skip_serializing_if = "String::is_empty")]
        pub description: String,

        /// Embedded literal example value. [`Example::value`] and [`Example::external_value`] are
        /// mutually exclusive.
        #[serde(skip_serializing_if = "Option::is_none")]
        pub value: Option<serde_json::Value>,

        /// An URI that points to a literal example value. [`Example::external_value`] provides the
        /// capability to references an example that cannot be easily included in JSON or YAML.
        /// [`Example::value`] and [`Example::external_value`] are mutually exclusive.
        #[serde(skip_serializing_if = "String::is_empty")]
        pub external_value: String,
    }
}

impl Example {
    /// Construct a new empty [`Example`]. This is effectively same as calling
    /// [`Example::default`].
    pub fn new() -> Self {
        Self::default()
    }
}

impl ExampleBuilder {
    /// Add or change a short description for the [`Example`]. Setting this to empty `String`
    /// will make it not render in the generated OpenAPI document.
    pub fn summary<S: Into<String>>(mut self, summary: S) -> Self {
        set_value!(self summary summary.into())
    }

    /// Add or change a long description for the [`Example`]. Markdown syntax is supported for rich
    /// text representation.
    ///
    /// Setting this to empty `String` will make it not render in the generated
    /// OpenAPI document.
    pub fn description<D: Into<String>>(mut self, description: D) -> Self {
        set_value!(self description description.into())
    }

    /// Add or change embedded literal example value. [`Example::value`] and [`Example::external_value`]
    /// are mutually exclusive.
    pub fn value(mut self, value: Option<serde_json::Value>) -> Self {
        set_value!(self value value)
    }

    /// Add or change an URI that points to a literal example value. [`Example::external_value`]
    /// provides the capability to references an example that cannot be easily included
    /// in JSON or YAML. [`Example::value`] and [`Example::external_value`] are mutually exclusive.
    ///
    /// Setting this to an empty String will make the field not to render in the generated OpenAPI
    /// document.
    pub fn external_value<E: Into<String>>(mut self, external_value: E) -> Self {
        set_value!(self external_value external_value.into())
    }
}

impl From<ExampleBuilder> for RefOr<Example> {
    fn from(example_builder: ExampleBuilder) -> Self {
        Self::T(example_builder.build())
    }
}