openapiv3_1/
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_derive::{Deserialize, Serialize};
8
9use super::RefOr;
10
11/// Implements [OpenAPI Example Object][example].
12///
13/// Example is used on path operations to describe possible response bodies.
14///
15/// [example]: https://spec.openapis.org/oas/latest.html#example-object
16#[non_exhaustive]
17#[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq, bon::Builder)]
18#[cfg_attr(feature = "debug", derive(Debug))]
19#[serde(rename_all = "camelCase")]
20#[builder(on(_, into))]
21pub struct Example {
22    /// Short description for the [`Example`].
23    #[serde(skip_serializing_if = "String::is_empty", default)]
24    pub summary: String,
25
26    /// Long description for the [`Example`]. Value supports markdown syntax for rich text
27    /// representation.
28    #[serde(skip_serializing_if = "String::is_empty", default)]
29    pub description: String,
30
31    /// Embedded literal example value. [`Example::value`] and [`Example::external_value`] are
32    /// mutually exclusive.
33    #[serde(skip_serializing_if = "Option::is_none", default)]
34    pub value: Option<serde_json::Value>,
35
36    /// An URI that points to a literal example value. [`Example::external_value`] provides the
37    /// capability to references an example that cannot be easily included in JSON or YAML.
38    /// [`Example::value`] and [`Example::external_value`] are mutually exclusive.
39    #[serde(skip_serializing_if = "String::is_empty", default)]
40    pub external_value: String,
41}
42
43impl Example {
44    /// Construct a new empty [`Example`]. This is effectively same as calling
45    /// [`Example::default`].
46    pub fn new() -> Self {
47        Self::default()
48    }
49}
50
51impl<S: example_builder::IsComplete> From<ExampleBuilder<S>> for Example {
52    fn from(builder: ExampleBuilder<S>) -> Self {
53        builder.build()
54    }
55}
56
57impl<S: example_builder::IsComplete> From<ExampleBuilder<S>> for RefOr<Example> {
58    fn from(builder: ExampleBuilder<S>) -> Self {
59        Self::T(builder.build())
60    }
61}
openapiv3_1/example.rs

openapiv3_1/
example.rs
