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