salvo_oapi/openapi/
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 serde::{Deserialize, Serialize};
5
6use super::{PropMap, Server};
7
8/// Implements [Open API Link Object][link_object] for responses.
9///
10/// The `Link` represents possible design time link for a response. It does not guarantee
11/// callers ability to invoke it but rather provides known relationship between responses and
12/// other operations.
13///
14/// For computing links, and providing instructions to execute them,
15/// a runtime [expression][expression] is used for accessing values in an operation
16/// and using them as parameters while invoking the linked operation.
17///
18/// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
19/// [link_object]: https://spec.openapis.org/oas/latest.html#link-object
20#[derive(Serialize, Deserialize, Clone, PartialEq, Default, Debug)]
21#[non_exhaustive]
22pub struct Link {
23    /// A relative or absolute URI reference to an OAS operation. This field is
24    /// mutually exclusive of the _`operation_id`_ field, and **must** point to an [Operation
25    /// Object][operation].
26    /// Relative _`operation_ref`_ values may be used to locate an existing [Operation
27    /// Object][operation] in the OpenAPI definition. See the rules for resolving [Relative
28    /// References][relative_references].
29    ///
30    /// [relative_references]: https://spec.openapis.org/oas/latest.html#relative-references-in-uris
31    /// [operation]: ../path/struct.Operation.html
32    #[serde(skip_serializing_if = "String::is_empty", default)]
33    pub operation_ref: String,
34
35    /// The name of an existing, resolvable OAS operation, as defined with a unique
36    /// _`operation_id`_.
37    /// This field is mutually exclusive of the _`operation_ref`_ field.
38    #[serde(skip_serializing_if = "String::is_empty", default)]
39    pub operation_id: String,
40
41    /// A map representing parameters to pass to an operation as specified with _`operation_id`_
42    /// or identified by _`operation_ref`_. The key is parameter name to be used and value can
43    /// be any value supported by JSON or an [expression][expression] e.g. `$path.id`
44    ///
45    /// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
46    #[serde(skip_serializing_if = "PropMap::is_empty")]
47    pub parameters: PropMap<String, serde_json::Value>,
48
49    /// A literal value or an [expression][expression] to be used as request body when operation is
50    /// called.
51    ///
52    /// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
53    #[serde(skip_serializing_if = "Option::is_none")]
54    pub request_body: Option<serde_json::Value>,
55
56    /// Description of the link. Value supports Markdown syntax.
57    #[serde(skip_serializing_if = "String::is_empty", default)]
58    pub description: String,
59
60    /// A [`Server`][server] object to be used by the target operation.
61    ///
62    /// [server]: ../server/struct.Server.html
63    #[serde(skip_serializing_if = "Option::is_none")]
64    pub server: Option<Server>,
65}
66
67impl Link {
68    /// Set a relative or absolute URI reference to an OAS operation. This field is
69    /// mutually exclusive of the _`operation_id`_ field, and **must** point to an [Operation
70    /// Object][operation].
71    ///
72    /// [operation]: ../path/struct.Operation.html
73    #[must_use]
74    pub fn operation_ref<S: Into<String>>(mut self, operation_ref: S) -> Self {
75        self.operation_ref = operation_ref.into();
76
77        self
78    }
79
80    /// Set the name of an existing, resolvable OAS operation, as defined with a unique
81    /// _`operation_id`_.
82    /// This field is mutually exclusive of the _`operation_ref`_ field.
83    #[must_use]
84    pub fn operation_id<S: Into<String>>(mut self, operation_id: S) -> Self {
85        self.operation_id = operation_id.into();
86
87        self
88    }
89
90    /// Add parameter to be passed to [Operation][operation] upon execution.
91    ///
92    /// [operation]: ../path/struct.Operation.html
93    #[must_use]
94    pub fn parameter<N: Into<String>, V: Into<serde_json::Value>>(
95        mut self,
96        name: N,
97        value: V,
98    ) -> Self {
99        self.parameters.insert(name.into(), value.into());
100
101        self
102    }
103
104    /// Set a literal value or an [expression][expression] to be used as request body when operation
105    /// is called.
106    ///
107    /// [expression]: https://spec.openapis.org/oas/latest.html#runtime-expressions
108    #[must_use]
109    pub fn request_body<B: Into<serde_json::Value>>(mut self, request_body: Option<B>) -> Self {
110        self.request_body = request_body.map(|request_body| request_body.into());
111
112        self
113    }
114
115    /// Set description of the link. Value supports Markdown syntax.
116    #[must_use]
117    pub fn description<S: Into<String>>(mut self, description: S) -> Self {
118        self.description = description.into();
119
120        self
121    }
122
123    /// Set a [`Server`][server] object to be used by the target operation.
124    ///
125    /// [server]: ../server/struct.Server.html
126    #[must_use]
127    pub fn server<S: Into<Server>>(mut self, server: Option<S>) -> Self {
128        self.server = server.map(|server| server.into());
129
130        self
131    }
132}
salvo_oapi/openapi/link.rs

salvo_oapi/openapi/
link.rs
