openapiv3_1/
link.rs

1//! Implements [Open API Link Object][link_object] for responses.
2//!
3//! [link_object]: https://spec.openapis.org/oas/latest.html#link-object
4use indexmap::IndexMap;
5use serde_derive::{Deserialize, Serialize};
6
7use super::Server;
8use super::extensions::Extensions;
9
10/// Implements [Open API Link Object][link_object] for responses.
11///
12/// The `Link` represents possible design time link for a response. It does not guarantee
13/// callers ability to invoke it but rather provides known relationship between responses and
14/// other operations.
15///
16/// For computing links, and providing instructions to execute them,
17/// a runtime [expression][expression] is used for accessing values in an operation
18/// and using them as parameters while invoking the linked operation.
19///
20/// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
21/// [link_object]: https://spec.openapis.org/oas/latest.html#link-object
22#[derive(Serialize, Deserialize, Clone, PartialEq, Default, bon::Builder)]
23#[cfg_attr(feature = "debug", derive(Debug))]
24#[builder(on(_, into))]
25#[non_exhaustive]
26pub struct Link {
27    /// A map representing parameters to pass to an operation as specified with _`operation_id`_
28    /// or identified by _`operation_ref`_. The key is parameter name to be used and value can
29    /// be any value supported by JSON or an [expression][expression] e.g. `$path.id`
30    ///
31    /// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
32    #[serde(skip_serializing_if = "IndexMap::is_empty", default)]
33    #[builder(field)]
34    pub parameters: IndexMap<String, serde_json::Value>,
35
36    /// A relative or absolute URI reference to an OAS operation. This field is
37    /// mutually exclusive of the _`operation_id`_ field, and **must** point to an [Operation
38    /// Object][operation].
39    /// Relative _`operation_ref`_ values may be used to locate an existing [Operation
40    /// Object][operation] in the OpenAPI definition. See the rules for resolving [Relative
41    /// References][relative_references].
42    ///
43    /// [relative_references]: https://spec.openapis.org/oas/latest.html#relative-references-in-uris
44    /// [operation]: ../path/struct.Operation.html
45    #[serde(skip_serializing_if = "String::is_empty", default)]
46    #[builder(default)]
47    pub operation_ref: String,
48
49    /// The name of an existing, resolvable OAS operation, as defined with a unique
50    /// _`operation_id`_.
51    /// This field is mutually exclusive of the _`operation_ref`_ field.
52    #[serde(skip_serializing_if = "String::is_empty", default)]
53    #[builder(default)]
54    pub operation_id: String,
55
56    /// A literal value or an [expression][expression] to be used as request body when operation is called.
57    ///
58    /// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
59    #[serde(skip_serializing_if = "Option::is_none", default)]
60    pub request_body: Option<serde_json::Value>,
61
62    /// Description of the link. Value supports Markdown syntax.
63    #[serde(skip_serializing_if = "String::is_empty", default)]
64    #[builder(default)]
65    pub description: String,
66
67    /// A [`Server`][server] object to be used by the target operation.
68    ///
69    /// [server]: ../server/struct.Server.html
70    #[serde(skip_serializing_if = "Option::is_none", default)]
71    pub server: Option<Server>,
72
73    /// Optional extensions "x-something".
74    #[serde(skip_serializing_if = "Option::is_none", default, flatten)]
75    pub extensions: Option<Extensions>,
76}
77
78impl<S: link_builder::State> LinkBuilder<S> {
79    /// Add parameters to be passed to [Operation][operation] upon execution.
80    ///
81    /// [operation]: ../path/struct.Operation.html
82    pub fn parameters<N: Into<String>, V: Into<serde_json::Value>>(self, items: impl IntoIterator<Item = (N, V)>) -> Self {
83        items.into_iter().fold(self, |this, (n, v)| this.parameter(n, v))
84    }
85
86    /// Add parameter to be passed to [Operation][operation] upon execution.
87    ///
88    /// [operation]: ../path/struct.Operation.html
89    pub fn parameter<N: Into<String>, V: Into<serde_json::Value>>(mut self, name: N, value: V) -> Self {
90        self.parameters.insert(name.into(), value.into());
91        self
92    }
93}
94
95impl<S: link_builder::IsComplete> From<LinkBuilder<S>> for Link {
96    fn from(builder: LinkBuilder<S>) -> Self {
97        builder.build()
98    }
99}
openapiv3_1/link.rs

openapiv3_1/
link.rs
