restify_openapi/models/paths.rs
1use crate::models::reference_or::ReferenceOr;
2use crate::models::security::SecurityRequirement;
3use crate::models::server::Server;
4use indexmap::IndexMap;
5use schemars::schema::Schema;
6use serde::Serialize;
7use serde_json::Value;
8use std::collections::BTreeMap;
9
10#[derive(Serialize, Clone, Debug, Default)]
11#[cfg_attr(
12 any(test, feature = "deserialize"),
13 derive(serde::Deserialize, PartialEq)
14)]
15#[serde(rename_all = "camelCase")]
16pub struct Paths {
17 #[serde(flatten)]
18 pub paths: IndexMap<String, PathItem>,
19 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
20 #[serde(
21 flatten,
22 skip_serializing_if = "IndexMap::is_empty",
23 skip_deserializing
24 )]
25 pub extensions: IndexMap<String, Value>,
26}
27
28/// Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-filtering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
29#[derive(Serialize, Clone, Debug, Default)]
30#[cfg_attr(
31 any(test, feature = "deserialize"),
32 derive(serde::Deserialize, PartialEq)
33)]
34#[serde(rename_all = "camelCase")]
35pub struct PathItem {
36 /// An optional, string summary, intended to apply to all operations in this path.
37 #[serde(skip_serializing_if = "Option::is_none")]
38 pub summary: Option<String>,
39 /// An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
40 #[serde(skip_serializing_if = "Option::is_none")]
41 pub description: Option<String>,
42 #[serde(flatten)]
43 pub operations: IndexMap<OperationType, Operation>,
44 /// An alternative `server` array to service all operations in this path.
45 #[serde(skip_serializing_if = "Vec::is_empty", default)]
46 pub server: Vec<Server>,
47 /// A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsParameters).
48 #[serde(skip_serializing_if = "Vec::is_empty", default)]
49 pub parameters: Vec<ReferenceOr<Parameter>>,
50 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
51 #[serde(
52 flatten,
53 skip_serializing_if = "IndexMap::is_empty",
54 skip_deserializing
55 )]
56 pub extensions: IndexMap<String, Value>,
57}
58
59#[derive(Serialize, Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
60#[cfg_attr(any(test, feature = "deserialize"), derive(serde::Deserialize))]
61#[serde(rename_all = "lowercase")]
62pub enum OperationType {
63 /// A definition of a GET operation on this path.
64 Get,
65 /// A definition of a PUT operation on this path.
66 Put,
67 /// A definition of a POST operation on this path.
68 Post,
69 /// A definition of a DELETE operation on this path.
70 Delete,
71 /// A definition of a OPTIONS operation on this path.
72 Options,
73 /// A definition of a HEAD operation on this path.
74 Head,
75 /// A definition of a PATCH operation on this path.
76 Patch,
77 /// A definition of a TRACE operation on this path.
78 Trace,
79}
80
81/// Describes a single API operation on a path.
82#[derive(Serialize, Clone, Debug, Default)]
83#[cfg_attr(
84 any(test, feature = "deserialize"),
85 derive(serde::Deserialize, PartialEq)
86)]
87#[serde(rename_all = "camelCase")]
88pub struct Operation {
89 /// A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
90 #[serde(skip_serializing_if = "Vec::is_empty", default)]
91 pub tags: Vec<String>,
92 /// A short summary of what the operation does.
93 #[serde(skip_serializing_if = "Option::is_none")]
94 pub summary: Option<String>,
95 /// A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
96 #[serde(skip_serializing_if = "Option::is_none")]
97 pub description: Option<String>,
98 /// Additional external documentation for this operation.
99 #[serde(skip_serializing_if = "Option::is_none")]
100 pub external_docs: Option<ExternalDocumentation>,
101 /// Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
102 #[serde(skip_serializing_if = "Option::is_none")]
103 pub operation_id: Option<String>,
104 /// A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsParameters).
105 #[serde(skip_serializing_if = "Vec::is_empty", default)]
106 pub parameters: Vec<ReferenceOr<Parameter>>,
107 /// The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
108 #[serde(skip_serializing_if = "Option::is_none")]
109 pub request_body: Option<ReferenceOr<RequestBody>>,
110 /// The list of possible responses as they are returned from executing this operation.
111 pub responses: Responses,
112 /// A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object). Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.
113 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
114 pub callbacks: BTreeMap<String, ReferenceOr<Callback>>,
115 /// Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
116 #[serde(skip_serializing_if = "Option::is_none")]
117 pub deprecated: Option<bool>,
118 /// A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.
119 #[serde(skip_serializing_if = "Vec::is_empty", default)]
120 pub security: Vec<SecurityRequirement>,
121 /// An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
122 #[serde(skip_serializing_if = "Vec::is_empty", default)]
123 pub servers: Vec<Server>,
124 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
125 #[serde(
126 flatten,
127 skip_serializing_if = "IndexMap::is_empty",
128 skip_deserializing
129 )]
130 pub extensions: IndexMap<String, Value>,
131}
132
133/// Allows referencing an external resource for extended documentation.
134#[derive(Serialize, Clone, Debug, Default)]
135#[cfg_attr(
136 any(test, feature = "deserialize"),
137 derive(serde::Deserialize, PartialEq)
138)]
139#[serde(rename_all = "camelCase")]
140pub struct ExternalDocumentation {
141 /// A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
142 #[serde(skip_serializing_if = "Option::is_none")]
143 pub description: Option<String>,
144 /// The URL for the target documentation. Value MUST be in the format of a URL.
145 pub url: String,
146 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
147 #[serde(
148 flatten,
149 skip_serializing_if = "IndexMap::is_empty",
150 skip_deserializing
151 )]
152 pub extensions: IndexMap<String, Value>,
153}
154
155/// Describes a single operation parameter.
156/// A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn).
157/// Parameter Locations
158/// # There are four possible parameter locations specified by the in field:
159///
160/// - path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
161/// - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
162/// - header - Custom headers that are expected as part of the request. Note that [RFC7230](https://datatracker.ietf.org/doc/html/rfc7230#page-22) states header names are case insensitive.
163/// - cookie - Used to pass a specific cookie value to the API.
164#[derive(Serialize, Clone, Debug, Default)]
165#[cfg_attr(
166 any(test, feature = "deserialize"),
167 derive(serde::Deserialize, PartialEq)
168)]
169#[serde(rename_all = "camelCase")]
170pub struct Parameter {
171 /// The name of the parameter. Parameter names are case sensitive.
172 /// - If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#paths-object). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-templating) for further information.
173 /// - If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
174 /// - For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn) property.
175 pub name: String,
176 /// The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.
177 #[serde(rename = "in")]
178 pub _in: ParameterIn,
179 /// A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
180 #[serde(skip_serializing_if = "Option::is_none")]
181 pub description: Option<String>,
182 /// Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
183 #[serde(skip_serializing_if = "Option::is_none")]
184 pub required: Option<bool>,
185 /// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
186 #[serde(skip_serializing_if = "Option::is_none")]
187 pub deprecated: Option<bool>,
188 /// Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
189 #[serde(skip_serializing_if = "Option::is_none")]
190 pub allow_empty_value: Option<bool>,
191 /// Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
192 #[serde(skip_serializing_if = "Option::is_none")]
193 pub style: Option<ParameterStyle>,
194 /// When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
195 #[serde(skip_serializing_if = "Option::is_none")]
196 pub explode: Option<bool>,
197 /// Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
198 #[serde(skip_serializing_if = "Option::is_none")]
199 pub allow_reserved: Option<bool>,
200 #[serde(flatten, skip_serializing_if = "Option::is_none")]
201 pub definition: Option<ParameterDefinition>,
202 #[serde(flatten, skip_serializing_if = "Option::is_none")]
203 pub example: Option<Examples>,
204 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
205 #[serde(
206 flatten,
207 skip_serializing_if = "IndexMap::is_empty",
208 skip_deserializing
209 )]
210 pub extensions: IndexMap<String, Value>,
211}
212
213#[derive(Serialize, Clone, Debug)]
214#[cfg_attr(
215 any(test, feature = "deserialize"),
216 derive(serde::Deserialize, PartialEq)
217)]
218#[serde(rename_all = "lowercase")]
219pub enum ParameterDefinition {
220 /// The schema defining the type used for the parameter.
221 Schema(ReferenceOr<Schema>),
222 /// A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.
223 Content(BTreeMap<String, MediaType>),
224}
225
226/// Each Media Type Object provides schema and examples for the media type identified by its key.
227#[derive(Serialize, Clone, Debug, Default)]
228#[cfg_attr(
229 any(test, feature = "deserialize"),
230 derive(serde::Deserialize, PartialEq)
231)]
232#[serde(rename_all = "camelCase")]
233pub struct MediaType {
234 /// The schema defining the content of the request, response, or parameter.
235 #[serde(skip_serializing_if = "Option::is_none")]
236 pub schema: Option<ReferenceOr<Schema>>,
237 #[serde(flatten)]
238 #[serde(skip_serializing_if = "Option::is_none")]
239 pub example: Option<Examples>,
240 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
241 pub encoding: BTreeMap<String, Encoding>,
242 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
243 #[serde(
244 flatten,
245 skip_serializing_if = "IndexMap::is_empty",
246 skip_deserializing
247 )]
248 pub extensions: IndexMap<String, Value>,
249}
250
251/// A single encoding definition applied to a single schema property.
252#[derive(Serialize, Clone, Debug, Default)]
253#[cfg_attr(
254 any(test, feature = "deserialize"),
255 derive(serde::Deserialize, PartialEq)
256)]
257#[serde(rename_all = "camelCase")]
258pub struct Encoding {
259 /// The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for object - `application/json`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
260 #[serde(skip_serializing_if = "Option::is_none")]
261 pub content_type: Option<String>,
262 /// A map allowing additional information to be provided as headers, for example `Content-Disposition`. `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`.
263 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
264 pub headers: BTreeMap<String, ReferenceOr<Header>>,
265 /// Describes how a specific property value will be serialized depending on its type. See [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object) for details on the [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
266 #[serde(skip_serializing_if = "Option::is_none")]
267 pub style: Option<ParameterStyle>,
268 /// When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
269 #[serde(skip_serializing_if = "Option::is_none")]
270 pub explode: Option<bool>,
271 /// Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
272 #[serde(skip_serializing_if = "Option::is_none")]
273 pub allow_reserved: Option<bool>,
274 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
275 #[serde(
276 flatten,
277 skip_serializing_if = "IndexMap::is_empty",
278 skip_deserializing
279 )]
280 pub extensions: IndexMap<String, Value>,
281}
282
283/// The Header Object follows the structure of the [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object) with the following changes:
284///
285/// 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
286/// 2. `in` MUST NOT be specified, it is implicitly in header.
287/// 3. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle)).
288#[derive(Serialize, Clone, Debug, Default)]
289#[cfg_attr(
290 any(test, feature = "deserialize"),
291 derive(serde::Deserialize, PartialEq)
292)]
293#[serde(rename_all = "camelCase")]
294pub struct Header {
295 /// Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
296 #[serde(skip_serializing_if = "Option::is_none")]
297 pub required: Option<bool>,
298 /// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
299 #[serde(skip_serializing_if = "Option::is_none")]
300 pub deprecated: Option<bool>,
301 /// A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
302 #[serde(skip_serializing_if = "Option::is_none")]
303 pub description: Option<String>,
304 #[serde(flatten, skip_serializing_if = "Option::is_none")]
305 pub definition: Option<ParameterDefinition>,
306 /// Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
307 #[serde(skip_serializing_if = "Option::is_none")]
308 pub style: Option<ParameterStyle>,
309}
310
311#[derive(Serialize, Clone, Debug, Eq, PartialEq)]
312#[cfg_attr(any(test, feature = "deserialize"), derive(serde::Deserialize))]
313#[serde(rename_all = "lowercase")]
314pub enum ParameterIn {
315 Query,
316 Header,
317 Path,
318 Cookie,
319}
320
321impl Default for ParameterIn {
322 fn default() -> Self {
323 Self::Path
324 }
325}
326
327#[derive(Serialize, Clone, Debug)]
328#[cfg_attr(
329 any(test, feature = "deserialize"),
330 derive(serde::Deserialize, PartialEq)
331)]
332#[serde(rename_all = "camelCase")]
333pub enum ParameterStyle {
334 /// Path-style parameters defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.7)
335 Matrix,
336 /// Label style parameters defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.5)
337 Label,
338 /// Form style parameters defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.8). This option replaces `collecztionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.
339 Form,
340 /// Simple style parameters defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.2). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.
341 Simple,
342 /// Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.
343 SpaceDelimited,
344 /// Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.
345 PipeDelimited,
346 /// Provides a simple way of rendering nested objects using form parameters.
347 DeepObject,
348}
349
350#[derive(Serialize, Clone, Debug)]
351#[cfg_attr(
352 any(test, feature = "deserialize"),
353 derive(serde::Deserialize, PartialEq)
354)]
355#[serde(rename_all = "camelCase")]
356pub enum Examples {
357 /// Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the example value SHALL override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
358 Example(Value),
359 /// Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the examples value SHALL override the `example` provided by the schema.
360 Examples(BTreeMap<String, ReferenceOr<Example>>),
361}
362
363#[derive(Serialize, Clone, Debug)]
364#[cfg_attr(
365 any(test, feature = "deserialize"),
366 derive(serde::Deserialize, PartialEq)
367)]
368#[serde(rename_all = "camelCase")]
369pub struct Example {
370 /// Short description for the example.
371 #[serde(skip_serializing_if = "Option::is_none")]
372 pub summary: Option<String>,
373 /// Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
374 #[serde(skip_serializing_if = "Option::is_none")]
375 pub description: Option<String>,
376 /// Embedded literal example. The `value` field and `externalValue field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
377 #[serde(flatten)]
378 pub value: ExampleValue,
379 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
380 #[serde(
381 flatten,
382 skip_serializing_if = "IndexMap::is_empty",
383 skip_deserializing
384 )]
385 pub extensions: IndexMap<String, Value>,
386}
387
388#[derive(Serialize, Clone, Debug)]
389#[cfg_attr(
390 any(test, feature = "deserialize"),
391 derive(serde::Deserialize, PartialEq)
392)]
393#[serde(rename_all = "camelCase")]
394pub enum ExampleValue {
395 /// Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
396 Value(Value),
397 /// A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive.
398 ExternalValue(String),
399}
400
401/// Describes a single request body.
402#[derive(Serialize, Clone, Debug, Default)]
403#[cfg_attr(
404 any(test, feature = "deserialize"),
405 derive(serde::Deserialize, PartialEq)
406)]
407#[serde(rename_all = "camelCase")]
408pub struct RequestBody {
409 /// A brief description of the request body. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
410 #[serde(skip_serializing_if = "Option::is_none")]
411 pub description: Option<String>,
412 /// The content of the request body. The key is a media type or [media type range](https://datatracker.ietf.org/doc/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
413 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
414 pub content: BTreeMap<String, MediaType>,
415 /// Determines if the request body is required in the request. Defaults to `false`.
416 #[serde(skip_serializing_if = "Option::is_none")]
417 pub required: Option<bool>,
418 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
419 #[serde(
420 flatten,
421 skip_serializing_if = "IndexMap::is_empty",
422 skip_deserializing
423 )]
424 pub extensions: IndexMap<String, Value>,
425}
426
427/// A container for the expected responses of an operation. The container maps a HTTP response code to the expected response.
428///
429/// The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.
430///
431/// The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification.
432///
433/// The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call.
434#[derive(Serialize, Clone, Debug, Default)]
435#[cfg_attr(
436 any(test, feature = "deserialize"),
437 derive(serde::Deserialize, PartialEq)
438)]
439#[serde(rename_all = "camelCase")]
440pub struct Responses {
441 /// The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object) can link to a response that the [OpenAPI Object's components/responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsResponses) section defines.
442 #[serde(skip_serializing_if = "Option::is_none")]
443 pub default: Option<ReferenceOr<Response>>,
444 #[serde(flatten, skip_serializing_if = "BTreeMap::is_empty")]
445 pub responses: BTreeMap<String, ReferenceOr<Response>>,
446 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
447 #[serde(
448 flatten,
449 skip_serializing_if = "IndexMap::is_empty",
450 skip_deserializing
451 )]
452 pub extensions: IndexMap<String, Value>,
453}
454
455/// Describes a single response from an API Operation, including design-time, static `links` to operations based on the response.
456#[derive(Serialize, Clone, Debug, Default)]
457#[cfg_attr(
458 any(test, feature = "deserialize"),
459 derive(serde::Deserialize, PartialEq)
460)]
461#[serde(rename_all = "camelCase")]
462pub struct Response {
463 /// A short description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
464 pub description: String,
465 /// Maps a header name to its definition. [RFC7230](https://datatracker.ietf.org/doc/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored.
466 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
467 pub headers: BTreeMap<String, ReferenceOr<Header>>,
468
469 /// A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://datatracker.ietf.org/doc/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
470 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
471 pub content: BTreeMap<String, MediaType>,
472 /// A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#components-object).
473 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
474 pub links: BTreeMap<String, ReferenceOr<Link>>,
475 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
476 #[serde(
477 flatten,
478 skip_serializing_if = "IndexMap::is_empty",
479 skip_deserializing
480 )]
481 pub extensions: IndexMap<String, Value>,
482}
483
484/// The `Link object` represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.
485///
486/// Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response.
487///
488/// For computing links, and providing instructions to execute them, a [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#runtime-expressions) is used for accessing values in an operation and using them as parameters while invoking the linked operation.
489#[derive(Serialize, Clone, Debug, Default)]
490#[cfg_attr(
491 any(test, feature = "deserialize"),
492 derive(serde::Deserialize, PartialEq)
493)]
494#[serde(rename_all = "camelCase")]
495pub struct Link {
496 #[serde(flatten, skip_serializing_if = "Option::is_none")]
497 pub operation_identifier: Option<OperationIdentifier>,
498 /// A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id).
499 #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
500 pub parameters: BTreeMap<String, AnyOrExpression>,
501 /// A literal value or [{expression}](/https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#runtime-expressions) to use as a request body when calling the target operation.
502 #[serde(skip_serializing_if = "Option::is_none")]
503 pub request_body: Option<AnyOrExpression>,
504 /// A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
505 #[serde(skip_serializing_if = "Option::is_none")]
506 pub description: Option<String>,
507 /// A server object to be used by the target operation.
508 #[serde(skip_serializing_if = "Option::is_none")]
509 pub server: Option<Server>,
510 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
511 #[serde(
512 flatten,
513 skip_serializing_if = "IndexMap::is_empty",
514 skip_deserializing
515 )]
516 pub extensions: IndexMap<String, Value>,
517}
518
519/// A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-item-object) that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
520#[derive(Serialize, Clone, Debug, Default)]
521#[cfg_attr(
522 any(test, feature = "deserialize"),
523 derive(serde::Deserialize, PartialEq)
524)]
525#[serde(rename_all = "camelCase")]
526pub struct Callback {
527 /// A Path Item Object used to define a callback request and expected responses. A [complete example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/callback-example.yaml) is available.
528 #[serde(flatten, skip_serializing_if = "BTreeMap::is_empty")]
529 pub callbacks: BTreeMap<String, PathItem>,
530 /// This object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions).
531 #[serde(
532 flatten,
533 skip_serializing_if = "IndexMap::is_empty",
534 skip_deserializing
535 )]
536 pub extensions: IndexMap<String, Value>,
537}
538
539#[derive(Serialize, Clone, Debug)]
540#[cfg_attr(
541 any(test, feature = "deserialize"),
542 derive(serde::Deserialize, PartialEq)
543)]
544#[serde(untagged)]
545pub enum AnyOrExpression {
546 Any(Value),
547 /// [{expression}](/https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#runtime-expressions)
548 Expression(String),
549}
550
551#[derive(Serialize, Clone, Debug)]
552#[cfg_attr(
553 any(test, feature = "deserialize"),
554 derive(serde::Deserialize, PartialEq)
555)]
556#[serde(rename_all = "camelCase")]
557pub enum OperationIdentifier {
558 /// A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object) in the OpenAPI definition.
559 OperationRef(String),
560 /// The name of an existing, resolvable OAS operation, as defined with a unique `operationId. This field is mutually exclusive of the `operationRef` field.
561 OperationId(String),
562}