asyncapi/
server.rs

1use indexmap::IndexMap;
2use serde::{Deserialize, Serialize};
3
4use crate::{ReferenceOr, ServerBinding};
5
6/// An object representing a message broker, a server or any other kind of
7/// computer program capable of sending and/or receiving data. This object is
8/// used to capture details such as URIs, protocols and security configuration.
9/// Variable substitution can be used so that some details, for example
10/// usernames and passwords, can be injected by code generation tools.
11///
12/// # Examples
13///
14/// A single server would be described as:
15/// ```json
16/// {
17///     "url": "development.gigantic-server.com",
18///     "description": "Development server",
19///     "protocol": "kafka",
20///     "protocolVersion": "1.0.0"
21/// }
22/// ```
23///
24/// ```yaml
25/// url: development.gigantic-server.com
26/// description: Development server
27/// protocol: kafka
28/// protocolVersion: '1.0.0'
29/// ```
30///
31/// The following shows how multiple servers can be described, for example,
32/// at the AsyncAPI Object's `servers`:
33///
34/// ```json
35/// {
36///     "servers": {
37///         "development": {
38///         "url": "development.gigantic-server.com",
39///         "description": "Development server",
40///         "protocol": "amqp",
41///         "protocolVersion": "0.9.1"
42///         },
43///         "staging": {
44///         "url": "staging.gigantic-server.com",
45///         "description": "Staging server",
46///         "protocol": "amqp",
47///         "protocolVersion": "0.9.1"
48///         },
49///         "production": {
50///         "url": "api.gigantic-server.com",
51///         "description": "Production server",
52///         "protocol": "amqp",
53///         "protocolVersion": "0.9.1"
54///         }
55///     }
56/// }
57/// ```
58///
59/// ```yaml
60/// servers:
61///   development:
62///     url: development.gigantic-server.com
63///     description: Development server
64///     protocol: amqp
65///     protocolVersion: 0.9.1
66///   staging:
67///     url: staging.gigantic-server.com
68///     description: Staging server
69///     protocol: amqp
70///     protocolVersion: 0.9.1
71///   production:
72///     url: api.gigantic-server.com
73///     description: Production server
74///     protocol: amqp
75///     protocolVersion: 0.9.1
76/// ```
77///
78/// The following shows how variables can be used for a server configuration:
79///
80/// ```json
81/// {
82///     "servers": {
83///         "production": {
84///             "url": "{username}.gigantic-server.com:{port}/{basePath}",
85///             "description": "The production API server",
86///             "protocol": "secure-mqtt",
87///             "variables": {
88///                 "username": {
89///                 "default": "demo",
90///                 "description": "This value is assigned by the service provider, in this example `gigantic-server.com`"
91///                 },
92///                 "port": {
93///                 "enum": [
94///                     "8883",
95///                     "8884"
96///                 ],
97///                 "default": "8883"
98///                 },
99///                 "basePath": {
100///                 "default": "v2"
101///                 }
102///             }
103///         }
104///     }
105/// }
106/// ```
107///
108/// ```yaml
109/// servers:
110///   production:
111///     url: '{username}.gigantic-server.com:{port}/{basePath}'
112///     description: The production API server
113///     protocol: secure-mqtt
114///     variables:
115///       username:
116///         # note! no enum here means it is an open value
117///         default: demo
118///         description: This value is assigned by the service provider, in this example `gigantic-server.com`
119///       port:
120///         enum:
121///           - '8883'
122///           - '8884'
123///         default: '8883'
124///       basePath:
125///         # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
126///         default: v2
127/// ```
128#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
129#[serde(rename_all = "camelCase")]
130pub struct Server {
131    /// **REQUIRED.** A URL to the target host. This URL supports Server
132    /// Variables and MAY be relative, to indicate that the host location is
133    /// relative to the location where the AsyncAPI document is being served.
134    /// Variable substitutions will be made when a variable is named in
135    /// `{`brackets`}`.
136    pub url: String,
137    /// **REQUIRED.** The protocol this URL supports for connection.
138    /// Supported protocol include, but are not limited to:
139    /// `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`,
140    /// `kafka-secure`, `mqtt`, `secure-mqtt`, `stomp`, `stomps`, `ws`,
141    /// `wss`, `mercure`.
142    pub protocol: String,
143    /// The version of the protocol used for connection.
144    /// For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc.
145    #[serde(skip_serializing_if = "Option::is_none")]
146    pub protocol_version: Option<String>,
147    /// An optional string describing the host designated by the URL.
148    /// [CommonMark syntax](https://spec.commonmark.org/) MAY be used
149    /// for rich text representation.
150    #[serde(skip_serializing_if = "Option::is_none")]
151    pub description: Option<String>,
152    /// A map between a variable name and its value. The value is used
153    /// for substitution in the server's URL template.
154    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
155    pub variables: IndexMap<String, ServerVariable>,
156    /// A declaration of which security mechanisms can be used with this
157    /// server. The list of values includes alternative security requirement
158    /// objects that can be used. Only one of the security requirement objects
159    /// need to be satisfied to authorize a connection or operation.
160    #[serde(default, skip_serializing_if = "Vec::is_empty")]
161    pub security: Vec<SecurityRequirement>,
162    /// A map where the keys describe the name of the protocol and the values
163    /// describe protocol-specific definitions for the server.
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub bindings: Option<ReferenceOr<ServerBinding>>,
166    /// This object MAY be extended with
167    /// [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).
168    #[serde(flatten)]
169    pub extensions: IndexMap<String, serde_json::Value>,
170}
171
172/// An object representing a Server Variable for server URL
173/// template substitution.
174#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
175#[serde(rename_all = "camelCase")]
176pub struct ServerVariable {
177    /// An enumeration of string values to be used if the substitution options are from a limited set.
178    #[serde(rename = "enum")]
179    #[serde(skip_serializing_if = "Option::is_none")]
180    pub en: Option<Vec<String>>,
181    /// The default value to use for substitution, and to send,
182    /// if an alternate value is not supplied.
183    #[serde(skip_serializing_if = "Option::is_none")]
184    pub default: Option<String>,
185    /// An optional description for the server variable.
186    /// [CommonMark syntax](https://spec.commonmark.org/)
187    /// MAY be used for rich text representation.
188    #[serde(skip_serializing_if = "Option::is_none")]
189    pub description: Option<String>,
190    /// An array of examples of the server variable.
191    #[serde(skip_serializing_if = "Option::is_none")]
192    pub examples: Option<Vec<String>>,
193    /// This object MAY be extended with
194    /// [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).
195    #[serde(flatten)]
196    pub extensions: IndexMap<String, serde_json::Value>,
197}
198
199/// Lists the required security schemes to execute this operation. The name
200/// used for each property MUST correspond to a security scheme declared in the
201/// Security Schemes under the Components Object.
202///
203/// When a list of Security Requirement Objects is defined on a Server object,
204/// only one of the Security Requirement Objects in the list needs to be
205/// satisfied to authorize the connection.
206///
207/// # Examples
208/// ## User/Password Security Requirement
209///
210/// ```json
211/// {
212///     "user_pass": []
213/// }
214/// ```
215///
216/// ```yaml
217/// user_pass: []
218/// ```
219///
220/// ## API Key Security Requirement
221///
222/// ```json
223/// {
224///     "api_key": []
225/// }
226/// ```
227///
228/// ```yaml
229/// api_key: []
230/// ```
231///
232/// ## OAuth2 Security Requirement
233///
234/// ```json
235/// {
236///     "petstore_auth": [
237///         "write:pets",
238///         "read:pets"
239///     ]
240/// }
241/// ```
242///
243/// ```yaml
244/// petstore_auth:
245/// - write:pets
246/// - read:pets
247/// ```
248#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
249#[serde(rename_all = "camelCase")]
250pub struct SecurityRequirement {
251    /// Each name MUST correspond to a security scheme which is declared in the
252    /// [Security Schemes][crate::SecurityScheme]
253    /// under the [Components Object][crate::Components].
254    /// If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then
255    /// the value is a list of scope names. Provide scopes that are required to
256    /// establish successful connection with the server. If scopes are not
257    /// needed, the list can be empty. For other security scheme types, the
258    /// array MUST be empty.
259    #[serde(flatten)]
260    pub values: IndexMap<String, Vec<String>>,
261}
asyncapi/server.rs

asyncapi/
server.rs
