apple_bloom/v3/
schema.rs

1//! Schema specification for [OpenAPI 3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.0.md)
2
3use crate::v3::extension::Extensions;
4use serde::{Deserialize, Serialize};
5use std::collections::{BTreeMap, HashMap};
6use url::Url;
7
8use crate::{
9    v3::components::{BooleanObjectOrReference, Components, ObjectOrReference},
10    Error, Result, MINIMUM_OPENAPI30_VERSION,
11};
12
13impl Spec {
14    pub fn validate_version(&self) -> Result<semver::Version> {
15        let spec_version = &self.openapi;
16        let sem_ver = semver::Version::parse(spec_version)?;
17        let required_version = semver::VersionReq::parse(MINIMUM_OPENAPI30_VERSION).unwrap();
18        if required_version.matches(&sem_ver) {
19            Ok(sem_ver)
20        } else {
21            Err(Error::UnsupportedSpecFileVersion(sem_ver))
22        }
23    }
24}
25
26/// top level document
27#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
28pub struct Spec {
29    /// This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html)
30    /// of the
31    /// [OpenAPI Specification version](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#versions)
32    /// that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling
33    /// specifications and clients to interpret the OpenAPI document. This is not related to
34    /// the API
35    /// [`info.version`](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#infoVersion)
36    /// string.
37    pub openapi: String,
38    /// Provides metadata about the API. The metadata MAY be used by tooling as required.
39    pub info: Info,
40    /// An array of Server Objects, which provide connectivity information to a target server.
41    /// If the `servers` property is not provided, or is an empty array, the default value would
42    /// be a
43    /// [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#serverObject)
44    /// with a
45    /// [url](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#serverUrl)
46    /// value of `/`.
47    // FIXME: Provide a default value as specified in documentation instead of `None`.
48    #[serde(skip_serializing_if = "Option::is_none")]
49    pub servers: Option<Vec<Server>>,
50
51    /// Holds the relative paths to the individual endpoints and their operations. The path is
52    /// appended to the URL from the
53    /// [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#serverObject)
54    /// in order to construct the full URL. The Paths MAY be empty, due to
55    /// [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#securityFiltering).
56    pub paths: BTreeMap<String, PathItem>,
57
58    /// An element to hold various schemas for the specification.
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub components: Option<Components>,
61
62    // FIXME: Implement
63    // /// A declaration of which security mechanisms can be used across the API.
64    // /// The list of  values includes alternative security requirement objects that can be used.
65    // /// Only one of the security requirement objects need to be satisfied to authorize a request.
66    // /// Individual operations can override this definition.
67    // #[serde(skip_serializing_if = "Option::is_none")]
68    // pub security: Option<SecurityRequirement>,
69    /// A list of tags used by the specification with additional metadata.
70    ///The order of the tags can be used to reflect on their order by the parsing tools.
71    /// Not all tags that are used by the
72    /// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#operationObject)
73    /// must be declared. The tags that are not declared MAY be organized randomly or
74    /// based on the tools' logic. Each tag name in the list MUST be unique.
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub tags: Option<Vec<Tag>>,
77
78    /// Additional external documentation.
79    #[serde(skip_serializing_if = "Option::is_none", rename = "externalDocs")]
80    pub external_docs: Option<ExternalDoc>,
81    #[serde(flatten)]
82    pub extensions: Extensions,
83}
84
85/// General information about the API.
86///
87///
88/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#infoObject>.
89#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
90// #[serde(rename_all = "lowercase")]
91pub struct Info {
92    /// The title of the application.
93    pub title: String,
94    /// A short description of the application. CommonMark syntax MAY be used for rich text representation.
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub description: Option<String>,
97    /// A URL to the Terms of Service for the API. MUST be in the format of a URL.
98    #[serde(rename = "termsOfService", skip_serializing_if = "Option::is_none")]
99    pub terms_of_service: Option<Url>,
100    /// The version of the OpenAPI document (which is distinct from the [OpenAPI Specification
101    /// version](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oasVersion)
102    /// or the API implementation version).
103    pub version: String,
104    /// The contact information for the exposed API.
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub contact: Option<Contact>,
107    /// The license information for the exposed API.
108    #[serde(skip_serializing_if = "Option::is_none")]
109    pub license: Option<License>,
110}
111
112/// Contact information for the exposed API.
113///
114/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#contactObject>.
115#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
116pub struct Contact {
117    #[serde(skip_serializing_if = "Option::is_none")]
118    pub name: Option<String>,
119
120    #[serde(skip_serializing_if = "Option::is_none")]
121    pub url: Option<Url>,
122
123    // TODO: Make sure the email is a valid email
124    #[serde(skip_serializing_if = "Option::is_none")]
125    pub email: Option<String>,
126    #[serde(flatten)]
127    pub extensions: Extensions,
128}
129
130/// License information for the exposed API.
131///
132/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#licenseObject>.
133#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
134pub struct License {
135    /// The license name used for the API.
136    pub name: String,
137    /// A URL to the license used for the API.
138    #[serde(skip_serializing_if = "Option::is_none")]
139    pub url: Option<Url>,
140    #[serde(flatten)]
141    pub extensions: Extensions,
142}
143
144/// An object representing a Server.
145///
146/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#serverObject>.
147#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
148pub struct Server {
149    /// A URL to the target host. This URL supports Server Variables and MAY be relative, to
150    /// indicate that the host location is relative to the location where the OpenAPI document
151    /// is being served. Variable substitutions will be made when a variable is named
152    /// in {brackets}.
153    pub url: String,
154    /// An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
155    #[serde(skip_serializing_if = "Option::is_none")]
156    pub description: Option<String>,
157    /// A map between a variable name and its value. The value is used for substitution in
158    /// the server's URL template.
159    #[serde(skip_serializing_if = "Option::is_none")]
160    pub variables: Option<BTreeMap<String, ServerVariable>>,
161}
162
163/// An object representing a Server Variable for server URL template substitution.
164///
165/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#serverVariableObject>.
166#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
167pub struct ServerVariable {
168    /// The default value to use for substitution, and to send, if an alternate value is not
169    /// supplied. Unlike the Schema Object's default, this value MUST be provided by the consumer.
170    pub default: String,
171    /// An enumeration of string values to be used if the substitution options are from a limited
172    /// set.
173    #[serde(rename = "enum", skip_serializing_if = "Option::is_none")]
174    pub substitutions_enum: Option<Vec<String>>,
175    /// An optional description for the server variable. [CommonMark] syntax MAY be used for rich
176    /// text representation.
177    ///
178    /// [CommonMark]: https://spec.commonmark.org/
179    #[serde(skip_serializing_if = "Option::is_none")]
180    pub description: Option<String>,
181}
182
183/// Describes the operations available on a single path.
184///
185/// A Path Item MAY be empty, due to [ACL
186/// constraints](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#securityFiltering).
187/// The path itself is still exposed to the documentation viewer but they will not know which
188/// operations and parameters are available.
189#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
190pub struct PathItem {
191    /// Allows for an external definition of this path item. The referenced structure MUST be
192    /// in the format of a
193    /// [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#pathItemObject).
194    /// If there are conflicts between the referenced definition and this Path Item's definition,
195    /// the behavior is undefined.
196    // FIXME: Should this ref be moved to an enum?
197    #[serde(skip_serializing_if = "Option::is_none", rename = "$ref")]
198    pub reference: Option<String>,
199
200    /// An optional, string summary, intended to apply to all operations in this path.
201    #[serde(skip_serializing_if = "Option::is_none")]
202    pub summary: Option<String>,
203    /// An optional, string description, intended to apply to all operations in this path.
204    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
205    #[serde(skip_serializing_if = "Option::is_none")]
206    pub description: Option<String>,
207
208    /// A definition of a GET operation on this path.
209    #[serde(skip_serializing_if = "Option::is_none")]
210    pub get: Option<Operation>,
211    /// A definition of a PUT operation on this path.
212    #[serde(skip_serializing_if = "Option::is_none")]
213    pub put: Option<Operation>,
214    /// A definition of a POST operation on this path.
215    #[serde(skip_serializing_if = "Option::is_none")]
216    pub post: Option<Operation>,
217    /// A definition of a DELETE operation on this path.
218    #[serde(skip_serializing_if = "Option::is_none")]
219    pub delete: Option<Operation>,
220    /// A definition of a OPTIONS operation on this path.
221    #[serde(skip_serializing_if = "Option::is_none")]
222    pub options: Option<Operation>,
223    /// A definition of a HEAD operation on this path.
224    #[serde(skip_serializing_if = "Option::is_none")]
225    pub head: Option<Operation>,
226    /// A definition of a PATCH operation on this path.
227    #[serde(skip_serializing_if = "Option::is_none")]
228    pub patch: Option<Operation>,
229    /// A definition of a TRACE operation on this path.
230    #[serde(skip_serializing_if = "Option::is_none")]
231    pub trace: Option<Operation>,
232
233    /// An alternative `server` array to service all operations in this path.
234    #[serde(skip_serializing_if = "Option::is_none")]
235    pub servers: Option<Vec<Server>>,
236
237    /// A list of parameters that are applicable for all the operations described under this
238    /// path. These parameters can be overridden at the operation level, but cannot be removed
239    /// there. The list MUST NOT include duplicated parameters. A unique parameter is defined by
240    /// a combination of a
241    /// [name](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterName)
242    /// and
243    /// [location](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterIn).
244    /// The list can use the
245    /// [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#referenceObject)
246    /// to link to parameters that are defined at the
247    /// [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#componentsParameters).
248    #[serde(skip_serializing_if = "Option::is_none")]
249    pub parameters: Option<Vec<ObjectOrReference<Parameter>>>,
250    #[serde(flatten)]
251    pub extensions: Extensions,
252}
253/// Describes a single API operation on a path.
254///
255/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#operationObject>.
256#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
257// #[serde(rename_all = "lowercase")]
258pub struct Operation {
259    /// A list of tags for API documentation control. Tags can be used for logical grouping of
260    /// operations by resources or any other qualifier.
261    #[serde(skip_serializing_if = "Option::is_none")]
262    pub tags: Option<Vec<String>>,
263    /// A short summary of what the operation does.
264    #[serde(skip_serializing_if = "Option::is_none")]
265    pub summary: Option<String>,
266    /// A verbose explanation of the operation behavior.
267    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
268    #[serde(skip_serializing_if = "Option::is_none")]
269    pub description: Option<String>,
270    /// Additional external documentation for this operation.
271    #[serde(skip_serializing_if = "Option::is_none", rename = "externalDocs")]
272    pub external_docs: Option<ExternalDoc>,
273    /// Unique string used to identify the operation. The id MUST be unique among all operations
274    /// described in the API. Tools and libraries MAY use the operationId to uniquely identify an
275    /// operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
276    #[serde(skip_serializing_if = "Option::is_none", rename = "operationId")]
277    pub operation_id: Option<String>,
278
279    /// A list of parameters that are applicable for this operation. If a parameter is already
280    /// defined at the
281    /// [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#pathItemParameters),
282    /// the new definition will override it but can never remove it. The list MUST NOT
283    /// include duplicated parameters. A unique parameter is defined by a combination of a
284    /// [name](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterName)
285    /// and
286    /// [location](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterIn).
287    /// The list can use the
288    /// [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#referenceObject)
289    /// to link to parameters that are defined at the
290    /// [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#componentsParameters).
291    #[serde(skip_serializing_if = "Option::is_none")]
292    pub parameters: Option<Vec<ObjectOrReference<Parameter>>>,
293
294    /// The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
295    #[serde(skip_serializing_if = "Option::is_none", rename = "requestBody")]
296    pub request_body: Option<ObjectOrReference<RequestBody>>,
297
298    /// The list of possible responses as they are returned from executing this operation.
299    ///
300    /// A container for the expected responses of an operation. The container maps a HTTP
301    /// response code to the expected response.
302    ///
303    /// The documentation is not necessarily expected to cover all possible HTTP response codes
304    /// because they may not be known in advance. However, documentation is expected to cover
305    /// a successful operation response and any known errors.
306    ///
307    /// The `default` MAY be used as a default response object for all HTTP codes that are not
308    /// covered individually by the specification.
309    ///
310    /// The `Responses Object` MUST contain at least one response code, and it SHOULD be the
311    /// response for a successful operation call.
312    ///
313    /// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#responsesObject>.
314    pub responses: BTreeMap<String, Response>,
315
316    /// A map of possible out-of band callbacks related to the parent operation. The key is
317    /// a unique identifier for the Callback Object. Each value in the map is a
318    /// [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#callbackObject)
319    /// that describes a request that may be initiated by the API provider and the
320    /// expected responses. The key value used to identify the callback object is
321    /// an expression, evaluated at runtime, that identifies a URL to use for the
322    /// callback operation.
323    #[serde(skip_serializing_if = "Option::is_none")]
324    pub callbacks: Option<BTreeMap<String, Callback>>,
325
326    /// Declares this operation to be deprecated. Consumers SHOULD refrain from usage
327    /// of the declared operation. Default value is `false`.
328    #[serde(skip_serializing_if = "Option::is_none")]
329    pub deprecated: Option<bool>,
330
331    // /// A declaration of which security mechanisms can be used for this operation. The list of
332    // /// values includes alternative security requirement objects that can be used. Only one
333    // /// of the security requirement objects need to be satisfied to authorize a request.
334    // /// This definition overrides any declared top-level
335    // /// [`security`](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oasSecurity).
336    // /// To remove a top-level security declaration, an empty array can be used.
337    pub security: Option<Vec<SecurityRequirement>>,
338    /// An alternative `server` array to service this operation. If an alternative `server`
339    /// object is specified at the Path Item Object or Root level, it will be overridden by
340    /// this value.
341    #[serde(skip_serializing_if = "Option::is_none")]
342    pub servers: Option<Vec<Server>>,
343    #[serde(flatten)]
344    pub extensions: Extensions,
345}
346
347// https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-requirement-object
348pub type SecurityRequirement = BTreeMap<String, Vec<String>>;
349
350#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
351pub enum ParameterLocation {
352    #[serde(rename = "path")]
353    Path,
354    #[serde(rename = "query")]
355    Query,
356    #[serde(rename = "header")]
357    Header,
358    #[serde(rename = "cookie")]
359    Cookie,
360}
361
362// FIXME: Verify against OpenAPI 3.0
363/// Describes a single operation parameter.
364/// A unique parameter is defined by a combination of a
365/// [name](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterName)
366/// and [location](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterIn).
367///
368/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterObject>.
369#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
370pub struct Parameter {
371    /// The name of the parameter.
372    pub name: String,
373    /// values depend on parameter type
374    /// may be `header`, `query`, 'path`, `formData`
375    #[serde(rename = "in")]
376    pub location: ParameterLocation,
377    #[serde(skip_serializing_if = "Option::is_none")]
378    pub required: Option<bool>,
379    #[serde(skip_serializing_if = "Option::is_none")]
380    pub schema: Option<Schema>,
381    #[serde(skip_serializing_if = "Option::is_none")]
382    #[serde(rename = "uniqueItems")]
383    pub unique_items: Option<bool>,
384    /// string, number, boolean, integer, array, file ( only for formData )
385    #[serde(skip_serializing_if = "Option::is_none")]
386    #[serde(rename = "type")]
387    pub param_type: Option<String>,
388    #[serde(skip_serializing_if = "Option::is_none")]
389    pub format: Option<String>,
390    /// A brief description of the parameter. This could contain examples
391    /// of use.  GitHub Flavored Markdown is allowed.
392    #[serde(skip_serializing_if = "Option::is_none")]
393    pub description: Option<String>,
394    // collectionFormat: ???
395    // default: ???
396    // maximum ?
397    // exclusiveMaximum ??
398    // minimum ??
399    // exclusiveMinimum ??
400    // maxLength ??
401    // minLength ??
402    // pattern ??
403    // maxItems ??
404    // minItems ??
405    // enum ??
406    // multipleOf ??
407    // allowEmptyValue ( for query / body params )
408    /// Describes how the parameter value will be serialized depending on the type of the parameter
409    /// value. Default values (based on value of in): for `query` - `form`; for `path` - `simple`; for
410    /// `header` - `simple`; for cookie - `form`.
411    #[serde(skip_serializing_if = "Option::is_none")]
412    pub style: Option<ParameterStyle>,
413}
414
415#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
416#[serde(rename_all = "camelCase")]
417pub enum ParameterStyle {
418    Matrix,
419    Label,
420    Form,
421    Simple,
422    SpaceDelimited,
423    PipeDelimited,
424    DeepObject,
425}
426
427// FIXME: Verify against OpenAPI 3.0
428/// The Schema Object allows the definition of input and output data types.
429/// These types can be objects, but also primitives and arrays.
430/// This object is an extended subset of the
431/// [JSON Schema Specification Wright Draft 00](http://json-schema.org/).
432/// For more information about the properties, see
433/// [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00) and
434/// [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00).
435/// Unless stated otherwise, the property definitions follow the JSON Schema.
436///
437/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#schemaObject>.
438#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default, Eq)]
439pub struct Schema {
440    /// [JSON reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
441    /// path to another definition
442    #[serde(skip_serializing_if = "Option::is_none")]
443    #[serde(rename = "$ref")]
444    pub ref_path: Option<String>,
445
446    #[serde(skip_serializing_if = "Option::is_none")]
447    pub description: Option<String>,
448
449    #[serde(skip_serializing_if = "Option::is_none")]
450    #[serde(rename = "type")]
451    pub schema_type: Option<String>,
452
453    #[serde(skip_serializing_if = "Option::is_none")]
454    pub format: Option<String>,
455
456    #[serde(skip_serializing_if = "Option::is_none")]
457    #[serde(rename = "enum")]
458    pub enum_values: Option<Vec<String>>,
459
460    #[serde(skip_serializing_if = "Option::is_none")]
461    pub required: Option<Vec<String>>,
462
463    #[serde(skip_serializing_if = "Option::is_none")]
464    pub items: Option<Box<Schema>>,
465
466    #[serde(skip_serializing_if = "Option::is_none")]
467    pub properties: Option<BTreeMap<String, Schema>>,
468
469    #[serde(skip_serializing_if = "Option::is_none", rename = "readOnly")]
470    pub read_only: Option<bool>,
471
472    #[serde(skip_serializing_if = "Option::is_none")]
473    pub nullable: Option<bool>,
474
475    /// Value can be boolean or object. Inline or referenced schema MUST be of a
476    /// [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#schemaObject)
477    /// and not a standard JSON Schema.
478    ///
479    /// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#properties>.
480    #[serde(
481        skip_serializing_if = "Option::is_none",
482        rename = "additionalProperties"
483    )]
484    pub additional_properties: Option<BooleanObjectOrReference<Box<Schema>>>,
485
486    /// A free-form property to include an example of an instance for this schema.
487    /// To represent examples that cannot be naturally represented in JSON or YAML,
488    /// a string value can be used to contain the example with escaping where necessary.
489    /// NOTE: According to [spec], _Primitive data types in the OAS are based on the
490    ///       types supported by the JSON Schema Specification Wright Draft 00._
491    ///       This suggest using
492    ///       [`serde_json::Value`](https://docs.serde.rs/serde_json/value/enum.Value.html). [spec][https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#data-types]
493    #[serde(skip_serializing_if = "Option::is_none")]
494    pub example: Option<serde_json::value::Value>,
495
496    #[serde(skip_serializing_if = "Option::is_none")]
497    pub title: Option<String>,
498
499    // The following properties are taken directly from the JSON Schema definition and
500    // follow the same specifications:
501    #[serde(skip_serializing_if = "Option::is_none", rename = "multipleOf")]
502    pub multiple_of: Option<u32>,
503
504    #[serde(skip_serializing_if = "Option::is_none")]
505    pub maximum: Option<i32>,
506
507    #[serde(skip_serializing_if = "Option::is_none", rename = "exclusiveMaximum")]
508    pub exclusive_maximum: Option<bool>,
509
510    #[serde(skip_serializing_if = "Option::is_none")]
511    pub minimum: Option<i32>,
512
513    #[serde(skip_serializing_if = "Option::is_none", rename = "exclusiveMinimum")]
514    pub exclusive_minimum: Option<bool>,
515
516    #[serde(skip_serializing_if = "Option::is_none", rename = "maxLength")]
517    pub max_length: Option<u32>,
518
519    #[serde(skip_serializing_if = "Option::is_none", rename = "minLength")]
520    pub min_length: Option<u32>,
521
522    #[serde(skip_serializing_if = "Option::is_none")]
523    pub pattern: Option<String>,
524
525    #[serde(skip_serializing_if = "Option::is_none", rename = "maxItems")]
526    pub max_items: Option<u32>,
527
528    #[serde(skip_serializing_if = "Option::is_none", rename = "minItems")]
529    pub min_items: Option<u32>,
530
531    #[serde(skip_serializing_if = "Option::is_none", rename = "uniqueItems")]
532    pub unique_items: Option<bool>,
533
534    #[serde(skip_serializing_if = "Option::is_none", rename = "maxProperties")]
535    pub max_properties: Option<u32>,
536
537    #[serde(skip_serializing_if = "Option::is_none", rename = "minProperties")]
538    pub min_properties: Option<u32>,
539
540    // The following properties are taken from the JSON Schema definition but their
541    // definitions were adjusted to the OpenAPI Specification.
542    // - type - Value MUST be a string. Multiple types via an array are not supported.
543    // - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
544    // - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
545    // - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
546    // - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
547    // - items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`.
548    // - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced).
549    // - additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
550    // - description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
551    // - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats.
552    // - default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
553    /// The default value represents what would be assumed by the consumer of the input as the value
554    /// of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the
555    /// defined type for the Schema Object defined at the same level. For example, if type is
556    /// `string`, then `default` can be `"foo"` but cannot be `1`.
557    #[serde(skip_serializing_if = "Option::is_none")]
558    pub default: Option<serde_json::Value>,
559
560    /// Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard
561    /// JSON Schema.
562    /// [allOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#allof)
563    #[serde(rename = "allOf", skip_serializing_if = "Option::is_none")]
564    pub all_of: Option<Vec<ObjectOrReference<Schema>>>,
565
566    /// Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard
567    /// JSON Schema.
568    /// [oneOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#oneof)
569    #[serde(rename = "oneOf", skip_serializing_if = "Option::is_none")]
570    pub one_of: Option<Vec<ObjectOrReference<Schema>>>,
571
572    /// Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard
573    /// JSON Schema.
574    /// [anyOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof)
575    #[serde(rename = "anyOf", skip_serializing_if = "Option::is_none")]
576    pub any_of: Option<Vec<ObjectOrReference<Schema>>>,
577
578    /// Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard
579    /// JSON Schema.
580    /// [not](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#not)
581    #[serde(rename = "not", skip_serializing_if = "Option::is_none")]
582    pub not: Option<Vec<ObjectOrReference<Schema>>>,
583
584    /// [Specification extensions](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.2.md#specificationExtensions)
585    #[serde(flatten)]
586    pub extensions: HashMap<String, String>,
587}
588
589/// Describes a single response from an API Operation, including design-time, static `links`
590/// to operations based on the response.
591///
592/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#responseObject>.
593#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
594pub struct Response {
595    /// A short description of the response.
596    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
597    pub description: Option<String>,
598
599    /// Maps a header name to its definition.
600    /// [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case
601    /// insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL
602    /// be ignored.
603    #[serde(skip_serializing_if = "Option::is_none")]
604    pub headers: Option<BTreeMap<String, ObjectOrReference<Header>>>,
605
606    /// A map containing descriptions of potential response payloads. The key is a media type
607    /// or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value
608    /// describes it. For responses that match multiple keys, only the most specific key is
609    /// applicable. e.g. text/plain overrides text/*
610    #[serde(skip_serializing_if = "Option::is_none")]
611    pub content: Option<BTreeMap<String, MediaType>>,
612
613    /// A map of operations links that can be followed from the response. The key of the map
614    /// is a short name for the link, following the naming constraints of the names for
615    /// [Component Objects](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#componentsObject).
616    #[serde(skip_serializing_if = "Option::is_none")]
617    pub links: Option<BTreeMap<String, ObjectOrReference<Link>>>,
618    #[serde(flatten)]
619    pub extensions: Extensions,
620}
621
622/// The Header Object follows the structure of the
623/// [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterObject)
624/// with the following changes:
625/// 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
626/// 1. `in` MUST NOT be specified, it is implicitly in `header`.
627/// 1. All traits that are affected by the location MUST be applicable to a location of
628///    `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterStyle)).
629///
630/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#headerObject>.
631#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
632pub struct Header {
633    // FIXME: Is the third change properly implemented?
634    // FIXME: Merge `ObjectOrReference<Header>::Reference` and `ParameterOrRef::Reference`
635    #[serde(skip_serializing_if = "Option::is_none")]
636    pub required: Option<bool>,
637    #[serde(skip_serializing_if = "Option::is_none")]
638    pub schema: Option<Schema>,
639    #[serde(skip_serializing_if = "Option::is_none")]
640    #[serde(rename = "uniqueItems")]
641    pub unique_items: Option<bool>,
642    /// string, number, boolean, integer, array, file ( only for formData )
643    #[serde(skip_serializing_if = "Option::is_none")]
644    #[serde(rename = "type")]
645    pub param_type: Option<String>,
646    #[serde(skip_serializing_if = "Option::is_none")]
647    pub format: Option<String>,
648    /// A brief description of the parameter. This could contain examples
649    /// of use.  GitHub Flavored Markdown is allowed.
650    #[serde(skip_serializing_if = "Option::is_none")]
651    pub description: Option<String>,
652    // collectionFormat: ???
653    // default: ???
654    // maximum ?
655    // exclusiveMaximum ??
656    // minimum ??
657    // exclusiveMinimum ??
658    // maxLength ??
659    // minLength ??
660    // pattern ??
661    // maxItems ??
662    // minItems ??
663    // enum ??
664    // multipleOf ??
665    // allowEmptyValue ( for query / body params )
666}
667
668/// Describes a single request body.
669///
670/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#requestBodyObject>.
671#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
672pub struct RequestBody {
673    /// A brief description of the request body. This could contain examples of use.
674    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
675    #[serde(skip_serializing_if = "Option::is_none")]
676    pub description: Option<String>,
677
678    /// The content of the request body. The key is a media type or
679    /// [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the
680    /// value describes it. For requests that match multiple keys, only the most specific key
681    /// is applicable. e.g. text/plain overrides text/*
682    pub content: BTreeMap<String, MediaType>,
683
684    #[serde(skip_serializing_if = "Option::is_none")]
685    pub required: Option<bool>,
686}
687
688/// The Link object represents a possible design-time link for a response.
689///
690/// The presence of a link does not guarantee the caller's ability to successfully invoke it,
691/// rather it provides a known relationship and traversal mechanism between responses and
692/// other operations.
693///
694/// Unlike _dynamic_ links (i.e. links provided *in* the response payload), the OAS linking
695/// mechanism does not require link information in the runtime response.
696///
697/// For computing links, and providing instructions to execute them, a
698/// [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#runtimeExpression)
699/// is used for accessing values in an operation and using them as parameters while invoking
700/// the linked operation.
701///
702/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#linkObject>.
703#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
704#[serde(untagged)]
705pub enum Link {
706    /// A relative or absolute reference to an OAS operation. This field is mutually exclusive
707    /// of the `operationId` field, and MUST point to an
708    /// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#operationObject).
709    /// Relative `operationRef` values MAY be used to locate an existing
710    /// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#operationObject)
711    /// in the OpenAPI definition.
712    Ref {
713        #[serde(rename = "operationRef")]
714        operation_ref: String,
715
716        // FIXME: Implement
717        // /// A map representing parameters to pass to an operation as specified with `operationId`
718        // /// or identified via `operationRef`. The key is the parameter name to be used, whereas
719        // /// the value can be a constant or an expression to be evaluated and passed to the
720        // /// linked operation. The parameter name can be qualified using the
721        // /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterIn)
722        // /// `[{in}.]{name}` for operations that use the same parameter name in different
723        // /// locations (e.g. path.id).
724        // parameters: BTreeMap<String, Any | {expression}>,
725        #[serde(skip_serializing_if = "Option::is_none")]
726        parameters: Option<BTreeMap<String, String>>,
727
728        // FIXME: Implement
729        // /// A literal value or
730        // /// [{expression}](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#runtimeExpression)
731        // /// to use as a request body when calling the target operation.
732        // #[serde(rename = "requestBody")]
733        // request_body: Any | {expression}
734        /// A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be
735        /// used for rich text representation.
736        #[serde(skip_serializing_if = "Option::is_none")]
737        description: Option<String>,
738
739        /// A server object to be used by the target operation.
740        #[serde(skip_serializing_if = "Option::is_none")]
741        server: Option<Server>,
742        #[serde(flatten)]
743        extensions: Extensions,
744    },
745    /// The name of an _existing_, resolvable OAS operation, as defined with a unique
746    /// `operationId`. This field is mutually exclusive of the `operationRef` field.
747    Id {
748        #[serde(rename = "operationId")]
749        operation_id: String,
750
751        // FIXME: Implement
752        // /// A map representing parameters to pass to an operation as specified with `operationId`
753        // /// or identified via `operationRef`. The key is the parameter name to be used, whereas
754        // /// the value can be a constant or an expression to be evaluated and passed to the
755        // /// linked operation. The parameter name can be qualified using the
756        // /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterIn)
757        // /// `[{in}.]{name}` for operations that use the same parameter name in different
758        // /// locations (e.g. path.id).
759        // parameters: BTreeMap<String, Any | {expression}>,
760        #[serde(skip_serializing_if = "Option::is_none")]
761        parameters: Option<BTreeMap<String, String>>,
762
763        // FIXME: Implement
764        // /// A literal value or
765        // /// [{expression}](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#runtimeExpression)
766        // /// to use as a request body when calling the target operation.
767        // #[serde(rename = "requestBody")]
768        // request_body: Any | {expression}
769        /// A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be
770        /// used for rich text representation.
771        #[serde(skip_serializing_if = "Option::is_none")]
772        description: Option<String>,
773
774        /// A server object to be used by the target operation.
775        #[serde(skip_serializing_if = "Option::is_none")]
776        server: Option<Server>,
777        #[serde(flatten)]
778        extensions: Extensions,
779    },
780}
781
782/// Each Media Type Object provides schema and examples for the media type identified by its key.
783///
784/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#media-type-object>.
785#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
786pub struct MediaType {
787    /// The schema defining the type used for the request body.
788    #[serde(skip_serializing_if = "Option::is_none")]
789    pub schema: Option<ObjectOrReference<Schema>>,
790
791    /// Example of the media type.
792    #[serde(flatten, skip_serializing_if = "Option::is_none")]
793    pub examples: Option<MediaTypeExample>,
794
795    /// A map between a property name and its encoding information. The key, being the
796    /// property name, MUST exist in the schema as a property. The encoding object SHALL
797    /// only apply to `requestBody` objects when the media type is `multipart`
798    /// or `application/x-www-form-urlencoded`.
799    #[serde(skip_serializing_if = "Option::is_none")]
800    pub encoding: Option<BTreeMap<String, Encoding>>,
801}
802
803#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
804#[serde(untagged)]
805pub enum MediaTypeExample {
806    /// Example of the media type. The example object SHOULD be in the correct format as
807    /// specified by the media type. The `example` field is mutually exclusive of the
808    /// `examples` field. Furthermore, if referencing a `schema` which contains an example,
809    /// the `example` value SHALL override the example provided by the schema.
810    Example { example: serde_json::Value },
811    /// Examples of the media type. Each example object SHOULD match the media type and
812    /// specified schema if present. The `examples` field is mutually exclusive of
813    /// the `example` field. Furthermore, if referencing a `schema` which contains an
814    /// example, the `examples` value SHALL override the example provided by the schema.
815    Examples {
816        examples: BTreeMap<String, ObjectOrReference<Example>>,
817    },
818}
819
820/// A single encoding definition applied to a single schema property.
821#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
822pub struct Encoding {
823    /// The Content-Type for encoding a specific property. Default value depends on the
824    /// property type: for `string` with `format` being `binary` – `application/octet-stream`;
825    /// for other primitive types – `text/plain`; for `object` - `application/json`;
826    /// for `array` – the default is defined based on the inner type. The value can be a
827    /// specific media type (e.g. `application/json`), a wildcard media type
828    /// (e.g. `image/*`), or a comma-separated list of the two types.
829    #[serde(skip_serializing_if = "Option::is_none", rename = "contentType")]
830    pub content_type: Option<String>,
831
832    /// A map allowing additional information to be provided as headers, for example
833    /// `Content-Disposition`.  `Content-Type` is described separately and SHALL be
834    /// ignored in this section. This property SHALL be ignored if the request body
835    /// media type is not a `multipart`.
836    #[serde(skip_serializing_if = "Option::is_none")]
837    pub headers: Option<BTreeMap<String, ObjectOrReference<Header>>>,
838
839    /// Describes how a specific property value will be serialized depending on its type.
840    /// See [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterObject)
841    /// for details on the
842    /// [`style`](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#parameterStyle)
843    /// property. The behavior follows the same values as `query` parameters, including
844    /// default values. This property SHALL be ignored if the request body media type
845    /// is not `application/x-www-form-urlencoded`.
846    #[serde(skip_serializing_if = "Option::is_none")]
847    pub style: Option<String>,
848
849    /// When this is true, property values of type `array` or `object` generate
850    /// separate parameters for each value of the array, or key-value-pair of the map.
851    /// For other types of properties this property has no effect. When
852    /// [`style`](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#encodingStyle)
853    /// is `form`, the default value is `true`. For all other styles, the default value
854    /// is `false`. This property SHALL be ignored if the request body media type is
855    /// not `application/x-www-form-urlencoded`.
856    #[serde(skip_serializing_if = "Option::is_none")]
857    pub explode: Option<bool>,
858
859    /// Determines whether the parameter value SHOULD allow reserved characters, as defined
860    /// by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=`
861    /// to be included without percent-encoding. The default value is `false`. This
862    /// property SHALL be ignored if the request body media type is
863    /// not `application/x-www-form-urlencoded`.
864    #[serde(skip_serializing_if = "Option::is_none", rename = "allowReserved")]
865    pub allow_reserved: Option<bool>,
866}
867
868/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#exampleObject>.
869#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
870pub struct Example {
871    /// Short description for the example.
872    #[serde(skip_serializing_if = "Option::is_none")]
873    pub summary: Option<String>,
874
875    /// Long description for the example.
876    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
877    #[serde(skip_serializing_if = "Option::is_none")]
878    pub description: Option<String>,
879    // FIXME: Implement (merge with externalValue as enum)
880    /// Embedded literal example. The `value` field and `externalValue` field are mutually
881    /// exclusive. To represent examples of media types that cannot naturally represented
882    /// in JSON or YAML, use a string value to contain the example, escaping where necessary.
883    #[serde(skip_serializing_if = "Option::is_none")]
884    pub value: Option<serde_json::Value>,
885    // FIXME: Implement (merge with value as enum)
886    // /// A URL that points to the literal example. This provides the capability to reference
887    // /// examples that cannot easily be included in JSON or YAML documents. The `value` field
888    // /// and `externalValue` field are mutually exclusive.
889    // #[serde(skip_serializing_if = "Option::is_none")]
890    // pub externalValue: Option<String>,
891    #[serde(flatten)]
892    pub extensions: Extensions,
893}
894
895/// Defines a security scheme that can be used by the operations. Supported schemes are
896/// HTTP authentication, an API key (either as a header or as a query parameter),
897///OAuth2's common flows (implicit, password, application and access code) as defined
898/// in [RFC6749](https://tools.ietf.org/html/rfc6749), and
899/// [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
900///
901/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#securitySchemeObject>.
902#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
903#[serde(tag = "type")]
904pub enum SecurityScheme {
905    #[serde(rename = "apiKey")]
906    ApiKey {
907        name: String,
908        #[serde(rename = "in")]
909        location: String,
910    },
911    #[serde(rename = "http")]
912    Http {
913        scheme: String,
914        #[serde(rename = "bearerFormat")]
915        bearer_format: Option<String>,
916    },
917    #[serde(rename = "oauth2")]
918    OAuth2 { flows: Box<Flows> },
919    #[serde(rename = "openIdConnect")]
920    OpenIdConnect {
921        #[serde(rename = "openIdConnectUrl")]
922        open_id_connect_url: String,
923    },
924}
925
926/// Allows configuration of the supported OAuth Flows.
927/// See [link]
928/// [link][https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oauth-flows-object]
929#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
930#[serde(rename_all = "camelCase")]
931pub struct Flows {
932    #[serde(skip_serializing_if = "Option::is_none")]
933    pub implicit: Option<ImplicitFlow>,
934    #[serde(skip_serializing_if = "Option::is_none")]
935    pub password: Option<PasswordFlow>,
936    #[serde(skip_serializing_if = "Option::is_none")]
937    pub client_credentials: Option<ClientCredentialsFlow>,
938    #[serde(skip_serializing_if = "Option::is_none")]
939    pub authorization_code: Option<AuthorizationCodeFlow>,
940}
941
942/// Configuration details for a implicit OAuth Flow
943/// See [link]
944/// [link](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oauth-flow-object)
945#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
946#[serde(rename_all = "camelCase")]
947pub struct ImplicitFlow {
948    pub authorization_url: Url,
949    #[serde(skip_serializing_if = "Option::is_none")]
950    pub refresh_url: Option<Url>,
951    pub scopes: BTreeMap<String, String>,
952}
953
954/// Configuration details for a password OAuth Flow
955/// See [link]
956/// [link](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oauth-flow-object
957#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
958#[serde(rename_all = "camelCase")]
959pub struct PasswordFlow {
960    token_url: Url,
961    #[serde(skip_serializing_if = "Option::is_none")]
962    pub refresh_url: Option<Url>,
963    pub scopes: BTreeMap<String, String>,
964}
965
966/// Configuration details for a client credentials OAuth Flow
967/// See [link]
968/// [link](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oauth-flow-object
969#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
970#[serde(rename_all = "camelCase")]
971pub struct ClientCredentialsFlow {
972    token_url: Url,
973    #[serde(skip_serializing_if = "Option::is_none")]
974    pub refresh_url: Option<Url>,
975    pub scopes: BTreeMap<String, String>,
976}
977
978/// Configuration details for a authorization code OAuth Flow
979/// See [link]
980/// [link](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oauth-flow-object
981#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
982#[serde(rename_all = "camelCase")]
983pub struct AuthorizationCodeFlow {
984    pub authorization_url: Url,
985    pub token_url: Url,
986    #[serde(skip_serializing_if = "Option::is_none")]
987    pub refresh_url: Option<Url>,
988    pub scopes: BTreeMap<String, String>,
989}
990
991// TODO: Implement
992/// A map of possible out-of band callbacks related to the parent operation. Each value in
993/// the map is a Path Item Object that describes a set of requests that may be initiated by
994/// the API provider and the expected responses. The key value used to identify the callback
995/// object is an expression, evaluated at runtime, that identifies a URL to use for the
996/// callback operation.
997///
998/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#callbackObject>.
999#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
1000pub struct Callback(
1001    /// A Path Item Object used to define a callback request and expected responses.
1002    serde_json::Value, // TODO: Add "Specification Extensions" https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#specificationExtensions}
1003);
1004
1005// FIXME: Implement
1006// /// Allows configuration of the supported OAuth Flows.
1007// /// https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#oauthFlowsObject
1008// #[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
1009// pub struct OAuthFlows {
1010// }
1011
1012/// Adds metadata to a single tag that is used by the
1013/// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#operationObject).
1014/// It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.
1015///
1016/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#tagObject>.
1017#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
1018pub struct Tag {
1019    /// The name of the tag.
1020    pub name: String,
1021
1022    /// A short description for the tag.
1023    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
1024    #[serde(skip_serializing_if = "Option::is_none")]
1025    pub description: Option<String>,
1026    // /// Additional external documentation for this tag.
1027    // #[serde(skip_serializing_if = "Option::is_none")]
1028    // pub external_docs: Option<Vec<ExternalDoc>>,
1029    #[serde(flatten)]
1030    pub extensions: Extensions,
1031}
1032
1033/// Allows referencing an external resource for extended documentation.
1034///
1035/// See <https://github.com/OAI/OpenAPI-Specification/blob/aa91a19c43f8a12c02efa42d64794e396473f3b1/versions/3.0.1.md#externalDocumentationObject>.
1036#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
1037pub struct ExternalDoc {
1038    /// The URL for the target documentation.
1039    pub url: Url,
1040
1041    /// A short description of the target documentation.
1042    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
1043    #[serde(skip_serializing_if = "Option::is_none")]
1044    pub description: Option<String>,
1045    #[serde(flatten)]
1046    pub extensions: Extensions,
1047}
1048
1049#[cfg(test)]
1050mod tests {
1051    use super::*;
1052
1053    #[test]
1054    fn test_security_scheme_oauth_deser() {
1055        const IMPLICIT_OAUTH2_SAMPLE: &str = r#"{
1056          "type": "oauth2",
1057          "flows": {
1058            "implicit": {
1059              "authorizationUrl": "https://example.com/api/oauth/dialog",
1060              "scopes": {
1061                "write:pets": "modify pets in your account",
1062                "read:pets": "read your pets"
1063              }
1064            },
1065            "authorizationCode": {
1066              "authorizationUrl": "https://example.com/api/oauth/dialog",
1067              "tokenUrl": "https://example.com/api/oauth/token",
1068              "scopes": {
1069                "write:pets": "modify pets in your account",
1070                "read:pets": "read your pets"
1071              }
1072            }
1073          }
1074        }"#;
1075        let obj: SecurityScheme = serde_json::from_str(&IMPLICIT_OAUTH2_SAMPLE).unwrap();
1076        match obj {
1077            SecurityScheme::OAuth2 { flows } => {
1078                assert!(flows.implicit.is_some());
1079                let implicit = flows.implicit.unwrap();
1080                assert_eq!(
1081                    implicit.authorization_url,
1082                    Url::parse("https://example.com/api/oauth/dialog").unwrap()
1083                );
1084                assert!(implicit.scopes.contains_key("write:pets"));
1085                assert!(implicit.scopes.contains_key("read:pets"));
1086
1087                assert!(flows.authorization_code.is_some());
1088                let auth_code = flows.authorization_code.unwrap();
1089                assert_eq!(
1090                    auth_code.authorization_url,
1091                    Url::parse("https://example.com/api/oauth/dialog").unwrap()
1092                );
1093                assert_eq!(
1094                    auth_code.token_url,
1095                    Url::parse("https://example.com/api/oauth/token").unwrap()
1096                );
1097                assert!(implicit.scopes.contains_key("write:pets"));
1098                assert!(implicit.scopes.contains_key("read:pets"));
1099            }
1100            _ => assert!(false, "wrong security scheme type"),
1101        }
1102    }
1103}
apple_bloom/v3/schema.rs

apple_bloom/v3/
schema.rs
