jsona_openapi/
openapi.rs

1use indexmap::IndexMap;
2use jsona_schema::Schema;
3use serde::{Deserialize, Serialize};
4
5/// top level document
6#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
7pub struct Openapi {
8    /// This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html)
9    /// of the
10    /// [OpenAPI Specification version](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#versions)
11    /// that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling
12    /// specifications and clients to interpret the OpenAPI document. This is not related to
13    /// the API
14    /// [`info.version`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoVersion)
15    /// string.
16    pub openapi: String,
17    /// Provides metadata about the API. The metadata MAY be used by tooling as required.
18    pub info: Info,
19    /// An array of Server Objects, which provide connectivity information to a target server.
20    /// If the `servers` property is not provided, or is an empty array, the default value would
21    /// be a
22    /// [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverObject)
23    /// with a
24    /// [url](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverUrl)
25    /// value of `/`.
26    // FIXME: Provide a default value as specified in documentation instead of `None`.
27    #[serde(skip_serializing_if = "Option::is_none")]
28    pub servers: Option<Vec<Server>>,
29    /// Additional external documentation.
30    /// A declaration of which security mechanisms can be used across the API.
31    /// The list of  values includes alternative security requirement objects that can be used.
32    /// Only one of the security requirement objects need to be satisfied to authorize a request.
33    /// Individual operations can override this definition.
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub security: Option<Vec<SecurityRequirement>>,
36    /// A list of tags used by the specification with additional metadata.
37    /// The order of the tags can be used to reflect on their order by the parsing tools.
38    /// Not all tags that are used by the
39    /// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject)
40    /// must be declared. The tags that are not declared MAY be organized randomly or
41    /// based on the tools' logic. Each tag name in the list MUST be unique.
42    #[serde(skip_serializing_if = "Option::is_none")]
43    pub tags: Option<Vec<Tag>>,
44    #[serde(skip_serializing_if = "Option::is_none", rename = "externalDocs")]
45    pub external_docs: Option<ExternalDoc>,
46    /// Holds the relative paths to the individual endpoints and their operations. The path is
47    /// appended to the URL from the
48    /// [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverObject)
49    /// in order to construct the full URL. The Paths MAY be empty, due to
50    /// [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securityFiltering).
51    pub paths: IndexMap<String, PathItem>,
52    /// An element to hold various schemas for the specification.
53    #[serde(skip_serializing_if = "Option::is_none")]
54    pub components: Option<Components>,
55}
56
57/// General information about the API.
58///
59///
60/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoObject>.
61#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
62// #[serde(rename_all = "lowercase")]
63pub struct Info {
64    /// The version of the OpenAPI document (which is distinct from the [OpenAPI Specification
65    /// version](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oasVersion)
66    /// or the API implementation version).
67    pub version: String,
68    /// The title of the application.
69    pub title: String,
70    /// A short description of the application. CommonMark syntax MAY be used for rich text representation.
71    #[serde(skip_serializing_if = "Option::is_none")]
72    pub description: Option<String>,
73    /// A URL to the Terms of Service for the API. MUST be in the format of a URL.
74    #[serde(rename = "termsOfService", skip_serializing_if = "Option::is_none")]
75    pub terms_of_service: Option<Url>,
76    /// The contact information for the exposed API.
77    #[serde(skip_serializing_if = "Option::is_none")]
78    pub contact: Option<Contact>,
79    /// The license information for the exposed API.
80    #[serde(skip_serializing_if = "Option::is_none")]
81    pub license: Option<License>,
82}
83
84/// Wraper around `url::Url` to fix serde issue
85#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
86pub struct Url(url::Url);
87
88impl Url {
89    pub fn parse<S: AsRef<str>>(input: S) -> std::result::Result<Url, url::ParseError> {
90        url::Url::parse(input.as_ref()).map(Url)
91    }
92}
93
94/// Contact information for the exposed API.
95///
96/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#contactObject>.
97#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
98pub struct Contact {
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub name: Option<String>,
101
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub url: Option<Url>,
104
105    // TODO: Make sure the email is a valid email
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub email: Option<String>,
108}
109
110/// License information for the exposed API.
111///
112/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#licenseObject>.
113#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
114pub struct License {
115    /// The license name used for the API.
116    pub name: String,
117    /// A URL to the license used for the API.
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub url: Option<Url>,
120}
121
122/// An object representing a Server.
123///
124/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverObject>.
125#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
126pub struct Server {
127    /// A URL to the target host. This URL supports Server Variables and MAY be relative, to
128    /// indicate that the host location is relative to the location where the OpenAPI document
129    /// is being served. Variable substitutions will be made when a variable is named
130    /// in {brackets}.
131    pub url: String,
132    /// An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
133    #[serde(skip_serializing_if = "Option::is_none")]
134    pub description: Option<String>,
135    /// A map between a variable name and its value. The value is used for substitution in
136    /// the server's URL template.
137    #[serde(skip_serializing_if = "Option::is_none")]
138    pub variables: Option<IndexMap<String, ServerVariable>>,
139}
140
141/// An object representing a Server Variable for server URL template substitution.
142///
143/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverVariableObject>.
144#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
145pub struct ServerVariable {
146    /// The default value to use for substitution, and to send, if an alternate value is not
147    /// supplied. Unlike the Schema Object's default, this value MUST be provided by the consumer.
148    pub default: String,
149    /// An enumeration of string values to be used if the substitution options are from a limited
150    /// set.
151    #[serde(rename = "enum", skip_serializing_if = "Option::is_none")]
152    pub substitutions_enum: Option<Vec<String>>,
153    /// An optional description for the server variable. [CommonMark] syntax MAY be used for rich
154    /// text representation.
155    ///
156    /// [CommonMark]: https://spec.commonmark.org/
157    #[serde(skip_serializing_if = "Option::is_none")]
158    pub description: Option<String>,
159}
160
161/// Holds a set of reusable objects for different aspects of the OAS.
162///
163/// All objects defined within the components object will have no effect on the API unless
164/// they are explicitly referenced from properties outside the components object.
165///
166/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#componentsObject>.
167#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
168pub struct Components {
169    /// An object to hold reusable Schema Objects.
170    #[serde(skip_serializing_if = "Option::is_none")]
171    pub schemas: Option<IndexMap<String, Schema>>,
172
173    /// An object to hold reusable Response Objects.
174    #[serde(skip_serializing_if = "Option::is_none")]
175    pub responses: Option<IndexMap<String, ObjectOrReference<Response>>>,
176
177    /// An object to hold reusable Parameter Objects.
178    #[serde(skip_serializing_if = "Option::is_none")]
179    pub parameters: Option<IndexMap<String, ObjectOrReference<Parameter>>>,
180
181    /// An object to hold reusable Example
182    #[serde(skip_serializing_if = "Option::is_none")]
183    pub examples: Option<IndexMap<String, ObjectOrReference<Example>>>,
184
185    /// An object to hold reusable Request Body Objects.
186    #[serde(skip_serializing_if = "Option::is_none", rename = "requestBodies")]
187    pub request_bodies: Option<IndexMap<String, ObjectOrReference<RequestBody>>>,
188
189    /// An object to hold reusable Header Objects.
190    #[serde(skip_serializing_if = "Option::is_none")]
191    pub headers: Option<IndexMap<String, ObjectOrReference<Header>>>,
192
193    /// An object to hold reusable Security Scheme Objects.
194    #[serde(skip_serializing_if = "Option::is_none", rename = "securitySchemes")]
195    pub security_schemes: Option<IndexMap<String, ObjectOrReference<SecurityScheme>>>,
196
197    /// An object to hold reusable Link Objects.
198    #[serde(skip_serializing_if = "Option::is_none")]
199    pub links: Option<IndexMap<String, ObjectOrReference<Link>>>,
200
201    /// An object to hold reusable Callback Objects.
202    #[serde(skip_serializing_if = "Option::is_none")]
203    pub callbacks: Option<IndexMap<String, ObjectOrReference<Callback>>>,
204}
205
206/// Describes the operations available on a single path.
207///
208/// A Path Item MAY be empty, due to [ACL
209/// constraints](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securityFiltering).
210/// The path itself is still exposed to the documentation viewer but they will not know which
211/// operations and parameters are available.
212#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
213pub struct PathItem {
214    /// Allows for an external definition of this path item. The referenced structure MUST be
215    /// in the format of a
216    /// [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#pathItemObject).
217    /// If there are conflicts between the referenced definition and this Path Item's definition,
218    /// the behavior is undefined.
219    // FIXME: Should this ref be moved to an enum?
220    #[serde(skip_serializing_if = "Option::is_none", rename = "$ref")]
221    pub reference: Option<String>,
222
223    /// An optional, string summary, intended to apply to all operations in this path.
224    #[serde(skip_serializing_if = "Option::is_none")]
225    pub summary: Option<String>,
226    /// An optional, string description, intended to apply to all operations in this path.
227    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
228    #[serde(skip_serializing_if = "Option::is_none")]
229    pub description: Option<String>,
230
231    /// A definition of a GET operation on this path.
232    #[serde(skip_serializing_if = "Option::is_none")]
233    pub get: Option<Operation>,
234    /// A definition of a PUT operation on this path.
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub put: Option<Operation>,
237    /// A definition of a POST operation on this path.
238    #[serde(skip_serializing_if = "Option::is_none")]
239    pub post: Option<Operation>,
240    /// A definition of a DELETE operation on this path.
241    #[serde(skip_serializing_if = "Option::is_none")]
242    pub delete: Option<Operation>,
243    /// A definition of a OPTIONS operation on this path.
244    #[serde(skip_serializing_if = "Option::is_none")]
245    pub options: Option<Operation>,
246    /// A definition of a HEAD operation on this path.
247    #[serde(skip_serializing_if = "Option::is_none")]
248    pub head: Option<Operation>,
249    /// A definition of a PATCH operation on this path.
250    #[serde(skip_serializing_if = "Option::is_none")]
251    pub patch: Option<Operation>,
252    /// A definition of a TRACE operation on this path.
253    #[serde(skip_serializing_if = "Option::is_none")]
254    pub trace: Option<Operation>,
255
256    /// An alternative `server` array to service all operations in this path.
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub servers: Option<Vec<Server>>,
259
260    /// A list of parameters that are applicable for all the operations described under this
261    /// path. These parameters can be overridden at the operation level, but cannot be removed
262    /// there. The list MUST NOT include duplicated parameters. A unique parameter is defined by
263    /// a combination of a
264    /// [name](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterName)
265    /// and
266    /// [location](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterIn).
267    /// The list can use the
268    /// [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#referenceObject)
269    /// to link to parameters that are defined at the
270    /// [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#componentsParameters).
271    #[serde(skip_serializing_if = "Option::is_none")]
272    pub parameters: Option<Vec<ObjectOrReference<Parameter>>>,
273}
274
275/// Describes a single API operation on a path.
276///
277/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject>.
278#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
279// #[serde(rename_all = "lowercase")]
280pub struct Operation {
281    /// A list of tags for API documentation control. Tags can be used for logical grouping of
282    /// operations by resources or any other qualifier.
283    #[serde(skip_serializing_if = "Option::is_none")]
284    pub tags: Option<Vec<String>>,
285    /// A short summary of what the operation does.
286    #[serde(skip_serializing_if = "Option::is_none")]
287    pub summary: Option<String>,
288    /// A verbose explanation of the operation behavior.
289    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
290    #[serde(skip_serializing_if = "Option::is_none")]
291    pub description: Option<String>,
292    /// Additional external documentation for this operation.
293    #[serde(skip_serializing_if = "Option::is_none", rename = "externalDocs")]
294    pub external_docs: Option<ExternalDoc>,
295    /// Unique string used to identify the operation. The id MUST be unique among all operations
296    /// described in the API. Tools and libraries MAY use the operationId to uniquely identify an
297    /// operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
298    #[serde(skip_serializing_if = "Option::is_none", rename = "operationId")]
299    pub operation_id: Option<String>,
300
301    #[serde(flatten, skip_serializing_if = "Option::is_none")]
302    pub extensions: Option<IndexMap<String, serde_json::Value>>,
303
304    /// A list of parameters that are applicable for this operation. If a parameter is already
305    /// defined at the
306    /// [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#pathItemParameters),
307    /// the new definition will override it but can never remove it. The list MUST NOT
308    /// include duplicated parameters. A unique parameter is defined by a combination of a
309    /// [name](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterName)
310    /// and
311    /// [location](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterIn).
312    /// The list can use the
313    /// [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#referenceObject)
314    /// to link to parameters that are defined at the
315    /// [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#componentsParameters).
316    #[serde(skip_serializing_if = "Option::is_none")]
317    pub parameters: Option<Vec<ObjectOrReference<Parameter>>>,
318
319    /// 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.
320    #[serde(skip_serializing_if = "Option::is_none", rename = "requestBody")]
321    pub request_body: Option<ObjectOrReference<RequestBody>>,
322
323    /// The list of possible responses as they are returned from executing this operation.
324    ///
325    /// A container for the expected responses of an operation. The container maps a HTTP
326    /// response code to the expected response.
327    ///
328    /// The documentation is not necessarily expected to cover all possible HTTP response codes
329    /// because they may not be known in advance. However, documentation is expected to cover
330    /// a successful operation response and any known errors.
331    ///
332    /// The `default` MAY be used as a default response object for all HTTP codes that are not
333    /// covered individually by the specification.
334    ///
335    /// The `Responses Object` MUST contain at least one response code, and it SHOULD be the
336    /// response for a successful operation call.
337    ///
338    /// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#responsesObject>.
339    pub responses: IndexMap<String, Response>,
340
341    /// A map of possible out-of band callbacks related to the parent operation. The key is
342    /// a unique identifier for the Callback Object. Each value in the map is a
343    /// [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#callbackObject)
344    /// that describes a request that may be initiated by the API provider and the
345    /// expected responses. The key value used to identify the callback object is
346    /// an expression, evaluated at runtime, that identifies a URL to use for the
347    /// callback operation.
348    #[serde(skip_serializing_if = "Option::is_none")]
349    pub callbacks: Option<IndexMap<String, Callback>>,
350
351    /// Declares this operation to be deprecated. Consumers SHOULD refrain from usage
352    /// of the declared operation. Default value is `false`.
353    #[serde(skip_serializing_if = "Option::is_none")]
354    pub deprecated: Option<bool>,
355
356    // /// A declaration of which security mechanisms can be used for this operation. The list of
357    // /// values includes alternative security requirement objects that can be used. Only one
358    // /// of the security requirement objects need to be satisfied to authorize a request.
359    // /// This definition overrides any declared top-level
360    // /// [`security`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oasSecurity).
361    // /// To remove a top-level security declaration, an empty array can be used.
362    #[serde(skip_serializing_if = "Option::is_none")]
363    pub security: Option<Vec<SecurityRequirement>>,
364    /// An alternative `server` array to service this operation. If an alternative `server`
365    /// object is specified at the Path Item Object or Root level, it will be overridden by
366    /// this value.
367    #[serde(skip_serializing_if = "Option::is_none")]
368    pub servers: Option<Vec<Server>>,
369}
370
371/// Allows referencing an external resource for extended documentation.
372///
373/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#externalDocumentationObject>.
374#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
375pub struct ExternalDoc {
376    /// The URL for the target documentation.
377    pub url: Url,
378
379    /// A short description of the target documentation.
380    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
381    #[serde(skip_serializing_if = "Option::is_none")]
382    pub description: Option<String>,
383}
384
385// FIXME: Verify against OpenAPI 3.0
386/// Describes a single operation parameter.
387/// A unique parameter is defined by a combination of a
388/// [name](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterName)
389/// and [location](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterIn).
390///
391/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterObject>.
392#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
393pub struct Parameter {
394    /// The name of the parameter.
395    pub name: String,
396    /// values depend on parameter type
397    /// may be `header`, `query`, 'path`, `formData`
398    #[serde(rename = "in")]
399    pub location: String,
400    /// A brief description of the parameter. This could contain examples
401    /// of use.  GitHub Flavored Markdown is allowed.
402    #[serde(skip_serializing_if = "Option::is_none")]
403    pub description: Option<String>,
404    #[serde(skip_serializing_if = "Option::is_none")]
405    pub required: Option<bool>,
406    /// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false.
407    #[serde(skip_serializing_if = "Option::is_none")]
408    pub deprecated: Option<bool>,
409    /// Sets the ability to pass empty-valued parameters.
410    /// This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false.
411    /// If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
412    /// Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
413    #[serde(rename = "allowEmptyValue", skip_serializing_if = "Option::is_none")]
414    pub allow_empty_value: Option<bool>,
415    /// Describes how the parameter value will be serialized depending on the type of the parameter
416    /// value. Default values (based on value of in): for `query` - `form`; for `path` - `simple`; for
417    /// `header` - `simple`; for cookie - `form`.
418    #[serde(skip_serializing_if = "Option::is_none")]
419    pub style: Option<ParameterStyle>,
420    /// When this is true, parameter values of type array or object generate separate parameters
421    /// for each value of the array or key-value pair of the map.
422    /// For other types of parameters this property has no effect.
423    /// When style is form, the default value is true.
424    /// For all other styles, the default value is false.
425    #[serde(skip_serializing_if = "Option::is_none")]
426    pub explode: Option<bool>,
427    /// Determines whether the parameter value SHOULD allow reserved characters
428    /// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
429    /// This property only applies to parameters with an in value of query. The default value is false.
430    #[serde(rename = "allowReserved", skip_serializing_if = "Option::is_none")]
431    pub allow_reserved: Option<bool>,
432    /// The schema defining the type used for the parameter.
433    #[serde(skip_serializing_if = "Option::is_none")]
434    pub schema: Option<Schema>,
435    /// Example of the parameter type.
436    #[serde(flatten, skip_serializing_if = "Option::is_none")]
437    pub examples: Option<OneOrMultiExample>,
438}
439
440#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
441#[serde(rename_all = "camelCase")]
442pub enum ParameterStyle {
443    Label,
444    Matrix,
445    Form,
446    Simple,
447    SpaceDelimited,
448    PipeDelimited,
449    DeepObject,
450}
451
452/// Describes a single request body.
453///
454/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#requestBodyObject>.
455#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
456pub struct RequestBody {
457    /// A brief description of the request body. This could contain examples of use.
458    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
459    #[serde(skip_serializing_if = "Option::is_none")]
460    pub description: Option<String>,
461
462    /// The content of the request body. The key is a media type or
463    /// [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the
464    /// value describes it. For requests that match multiple keys, only the most specific key
465    /// is applicable. e.g. text/plain overrides text/*
466    pub content: IndexMap<String, MediaType>,
467
468    #[serde(skip_serializing_if = "Option::is_none")]
469    pub required: Option<bool>,
470}
471
472/// Each Media Type Object provides schema and examples for the media type identified by its key.
473///
474/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#media-type-object>.
475#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
476pub struct MediaType {
477    /// The schema defining the type used for the request body.
478    #[serde(skip_serializing_if = "Option::is_none")]
479    pub schema: Option<Schema>,
480
481    /// Example of the media type.
482    #[serde(flatten, skip_serializing_if = "Option::is_none")]
483    pub examples: Option<OneOrMultiExample>,
484
485    /// A map between a property name and its encoding information. The key, being the
486    /// property name, MUST exist in the schema as a property. The encoding object SHALL
487    /// only apply to `requestBody` objects when the media type is `multipart`
488    /// or `application/x-www-form-urlencoded`.
489    #[serde(skip_serializing_if = "Option::is_none")]
490    pub encoding: Option<IndexMap<String, Encoding>>,
491}
492
493/// A single encoding definition applied to a single schema property.
494#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
495pub struct Encoding {
496    /// The Content-Type for encoding a specific property. Default value depends on the
497    /// property type: for `string` with `format` being `binary` – `application/octet-stream`;
498    /// for other primitive types – `text/plain`; for `object` - `application/json`;
499    /// for `array` – the default is defined based on the inner type. The value can be a
500    /// specific media type (e.g. `application/json`), a wildcard media type
501    /// (e.g. `image/*`), or a comma-separated list of the two types.
502    #[serde(skip_serializing_if = "Option::is_none", rename = "contentType")]
503    pub content_type: Option<String>,
504
505    /// A map allowing additional information to be provided as headers, for example
506    /// `Content-Disposition`.  `Content-Type` is described separately and SHALL be
507    /// ignored in this section. This property SHALL be ignored if the request body
508    /// media type is not a `multipart`.
509    #[serde(skip_serializing_if = "Option::is_none")]
510    pub headers: Option<IndexMap<String, ObjectOrReference<Header>>>,
511
512    /// Describes how a specific property value will be serialized depending on its type.
513    /// See [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterObject)
514    /// for details on the
515    /// [`style`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterStyle)
516    /// property. The behavior follows the same values as `query` parameters, including
517    /// default values. This property SHALL be ignored if the request body media type
518    /// is not `application/x-www-form-urlencoded`.
519    #[serde(skip_serializing_if = "Option::is_none")]
520    pub style: Option<ParameterStyle>,
521
522    /// When this is true, property values of type `array` or `object` generate
523    /// separate parameters for each value of the array, or key-value-pair of the map.
524    /// For other types of properties this property has no effect. When
525    /// [`style`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#encodingStyle)
526    /// is `form`, the default value is `true`. For all other styles, the default value
527    /// is `false`. This property SHALL be ignored if the request body media type is
528    /// not `application/x-www-form-urlencoded`.
529    #[serde(skip_serializing_if = "Option::is_none")]
530    pub explode: Option<bool>,
531
532    /// Determines whether the parameter value SHOULD allow reserved characters, as defined
533    /// by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=`
534    /// to be included without percent-encoding. The default value is `false`. This
535    /// property SHALL be ignored if the request body media type is
536    /// not `application/x-www-form-urlencoded`.
537    #[serde(skip_serializing_if = "Option::is_none", rename = "allowReserved")]
538    pub allow_reserved: Option<bool>,
539}
540
541/// Describes a single response from an API Operation, including design-time, static `links`
542/// to operations based on the response.
543///
544/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#responseObject>.
545#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
546pub struct Response {
547    /// A short description of the response.
548    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
549    pub description: String,
550
551    /// Maps a header name to its definition.
552    /// [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case
553    /// insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL
554    /// be ignored.
555    #[serde(skip_serializing_if = "Option::is_none")]
556    pub headers: Option<IndexMap<String, ObjectOrReference<Header>>>,
557
558    /// A map containing descriptions of potential response payloads. The key is a media type
559    /// or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value
560    /// describes it. For responses that match multiple keys, only the most specific key is
561    /// applicable. e.g. text/plain overrides text/*
562    #[serde(skip_serializing_if = "Option::is_none")]
563    pub content: Option<IndexMap<String, MediaType>>,
564
565    /// A map of operations links that can be followed from the response. The key of the map
566    /// is a short name for the link, following the naming constraints of the names for
567    /// [Component Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#componentsObject).
568    #[serde(skip_serializing_if = "Option::is_none")]
569    pub links: Option<IndexMap<String, ObjectOrReference<Link>>>,
570}
571
572/// A map of possible out-of band callbacks related to the parent operation. Each value in
573/// the map is a Path Item Object that describes a set of requests that may be initiated by
574/// the API provider and the expected responses. The key value used to identify the callback
575/// object is an expression, evaluated at runtime, that identifies a URL to use for the
576/// callback operation.
577///
578/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#callbackObject>.
579#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
580pub struct Callback(
581    /// A Path Item Object used to define a callback request and expected responses.
582    serde_json::Value,
583);
584
585#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
586#[serde(untagged)]
587pub enum OneOrMultiExample {
588    /// Example of the media type. The example object SHOULD be in the correct format as
589    /// specified by the media type. The `example` field is mutually exclusive of the
590    /// `examples` field. Furthermore, if referencing a `schema` which contains an example,
591    /// the `example` value SHALL override the example provided by the schema.
592    Example { example: serde_json::Value },
593    /// Examples of the media type. Each example object SHOULD match the media type and
594    /// specified schema if present. The `examples` field is mutually exclusive of
595    /// the `example` field. Furthermore, if referencing a `schema` which contains an
596    /// example, the `examples` value SHALL override the example provided by the schema.
597    Examples {
598        examples: IndexMap<String, ObjectOrReference<Example>>,
599    },
600}
601
602/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#exampleObject>.
603#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
604pub struct Example {
605    /// Short description for the example.
606    #[serde(skip_serializing_if = "Option::is_none")]
607    pub summary: Option<String>,
608
609    /// Long description for the example.
610    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
611    #[serde(skip_serializing_if = "Option::is_none")]
612    pub description: Option<String>,
613    // FIXME: Implement (merge with externalValue as enum)
614    /// Embedded literal example. The `value` field and `externalValue` field are mutually
615    /// exclusive. To represent examples of media types that cannot naturally represented
616    /// in JSON or YAML, use a string value to contain the example, escaping where necessary.
617    #[serde(skip_serializing_if = "Option::is_none")]
618    pub value: Option<serde_json::Value>,
619    // FIXME: Implement (merge with value as enum)
620    // /// A URL that points to the literal example. This provides the capability to reference
621    // /// examples that cannot easily be included in JSON or YAML documents. The `value` field
622    // /// and `externalValue` field are mutually exclusive.
623    // #[serde(skip_serializing_if = "Option::is_none")]
624    // pub externalValue: Option<String>,
625
626    // TODO: Add "Specification Extensions" https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#specificationExtensions}
627}
628
629/// The Link object represents a possible design-time link for a response.
630///
631/// The presence of a link does not guarantee the caller's ability to successfully invoke it,
632/// rather it provides a known relationship and traversal mechanism between responses and
633/// other operations.
634///
635/// Unlike _dynamic_ links (i.e. links provided *in* the response payload), the OAS linking
636/// mechanism does not require link information in the runtime response.
637///
638/// For computing links, and providing instructions to execute them, a
639/// [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#runtimeExpression)
640/// is used for accessing values in an operation and using them as parameters while invoking
641/// the linked operation.
642///
643/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#linkObject>.
644#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
645#[serde(untagged)]
646pub enum Link {
647    /// A relative or absolute reference to an OAS operation. This field is mutually exclusive
648    /// of the `operationId` field, and MUST point to an
649    /// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject).
650    /// Relative `operationRef` values MAY be used to locate an existing
651    /// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject)
652    /// in the OpenAPI definition.
653    Ref {
654        #[serde(rename = "operationRef")]
655        operation_ref: String,
656
657        // FIXME: Implement
658        // /// A map representing parameters to pass to an operation as specified with `operationId`
659        // /// or identified via `operationRef`. The key is the parameter name to be used, whereas
660        // /// the value can be a constant or an expression to be evaluated and passed to the
661        // /// linked operation. The parameter name can be qualified using the
662        // /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterIn)
663        // /// `[{in}.]{name}` for operations that use the same parameter name in different
664        // /// locations (e.g. path.id).
665        // parameters: IndexMap<String, Any | {expression}>,
666        #[serde(skip_serializing_if = "Option::is_none")]
667        parameters: Option<IndexMap<String, String>>,
668
669        // FIXME: Implement
670        // /// A literal value or
671        // /// [{expression}](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#runtimeExpression)
672        // /// to use as a request body when calling the target operation.
673        // #[serde(rename = "requestBody")]
674        // request_body: Any | {expression}
675        /// A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be
676        /// used for rich text representation.
677        #[serde(skip_serializing_if = "Option::is_none")]
678        description: Option<String>,
679
680        /// A server object to be used by the target operation.
681        #[serde(skip_serializing_if = "Option::is_none")]
682        server: Option<Server>,
683        // TODO: Add "Specification Extensions" https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#specificationExtension
684    },
685    /// The name of an _existing_, resolvable OAS operation, as defined with a unique
686    /// `operationId`. This field is mutually exclusive of the `operationRef` field.
687    Id {
688        #[serde(rename = "operationId")]
689        operation_id: String,
690
691        // FIXME: Implement
692        // /// A map representing parameters to pass to an operation as specified with `operationId`
693        // /// or identified via `operationRef`. The key is the parameter name to be used, whereas
694        // /// the value can be a constant or an expression to be evaluated and passed to the
695        // /// linked operation. The parameter name can be qualified using the
696        // /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterIn)
697        // /// `[{in}.]{name}` for operations that use the same parameter name in different
698        // /// locations (e.g. path.id).
699        // parameters: IndexMap<String, Any | {expression}>,
700        #[serde(skip_serializing_if = "Option::is_none")]
701        parameters: Option<IndexMap<String, String>>,
702
703        // FIXME: Implement
704        // /// A literal value or
705        // /// [{expression}](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#runtimeExpression)
706        // /// to use as a request body when calling the target operation.
707        // #[serde(rename = "requestBody")]
708        // request_body: Any | {expression}
709        /// A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be
710        /// used for rich text representation.
711        #[serde(skip_serializing_if = "Option::is_none")]
712        description: Option<String>,
713
714        /// A server object to be used by the target operation.
715        #[serde(skip_serializing_if = "Option::is_none")]
716        server: Option<Server>,
717        // TODO: Add "Specification Extensions" https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#specificationExtension
718    },
719}
720
721/// The Header Object follows the structure of the
722/// [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterObject)
723/// with the following changes:
724/// 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
725/// 1. `in` MUST NOT be specified, it is implicitly in `header`.
726/// 1. All traits that are affected by the location MUST be applicable to a location of
727///    `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterStyle)).
728///
729/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#headerObject>.
730#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
731pub struct Header {
732    /// A brief description of the parameter. This could contain examples
733    /// of use.  GitHub Flavored Markdown is allowed.
734    #[serde(skip_serializing_if = "Option::is_none")]
735    pub description: Option<String>,
736    #[serde(skip_serializing_if = "Option::is_none")]
737    pub required: Option<bool>,
738    /// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false.
739    #[serde(skip_serializing_if = "Option::is_none")]
740    pub deprecated: Option<bool>,
741    /// Sets the ability to pass empty-valued parameters.
742    /// This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false.
743    /// If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
744    /// Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
745    #[serde(rename = "allowEmptyValue", skip_serializing_if = "Option::is_none")]
746    pub allow_empty_value: Option<bool>,
747    /// Describes how the parameter value will be serialized depending on the type of the parameter
748    /// value. Default values (based on value of in): for `query` - `form`; for `path` - `simple`; for
749    /// `header` - `simple`; for cookie - `form`.
750    #[serde(skip_serializing_if = "Option::is_none")]
751    pub style: Option<ParameterStyle>,
752    /// When this is true, parameter values of type array or object generate separate parameters
753    /// for each value of the array or key-value pair of the map.
754    /// For other types of parameters this property has no effect.
755    /// When style is form, the default value is true.
756    /// For all other styles, the default value is false.
757    #[serde(skip_serializing_if = "Option::is_none")]
758    pub explode: Option<bool>,
759    /// Determines whether the parameter value SHOULD allow reserved characters
760    /// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
761    /// This property only applies to parameters with an in value of query. The default value is false.
762    #[serde(rename = "allowReserved", skip_serializing_if = "Option::is_none")]
763    pub allow_reserved: Option<bool>,
764    /// The schema defining the type used for the parameter.
765    #[serde(skip_serializing_if = "Option::is_none")]
766    pub schema: Option<Schema>,
767    /// Example of the parameter type.
768    #[serde(flatten, skip_serializing_if = "Option::is_none")]
769    pub examples: Option<OneOrMultiExample>,
770}
771
772/// Adds metadata to a single tag that is used by the
773/// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject).
774/// It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.
775///
776/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#tagObject>.
777#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
778pub struct Tag {
779    /// The name of the tag.
780    pub name: String,
781    /// A short description for the tag.
782    /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
783    #[serde(skip_serializing_if = "Option::is_none")]
784    pub description: Option<String>,
785    /// Additional external documentation for this tag.
786    #[serde(skip_serializing_if = "Option::is_none")]
787    pub external_docs: Option<Vec<ExternalDoc>>,
788}
789
790/// A simple object to allow referencing other components in the specification, internally and externally.
791#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
792#[serde(untagged)]
793pub enum ObjectOrReference<T> {
794    Object(T),
795    Ref {
796        #[serde(rename = "$ref")]
797        ref_path: String,
798    },
799}
800
801/// Defines a security scheme that can be used by the operations. Supported schemes are
802/// HTTP authentication, an API key (either as a header or as a query parameter),
803///OAuth2's common flows (implicit, password, application and access code) as defined
804/// in [RFC6749](https://tools.ietf.org/html/rfc6749), and
805/// [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
806///
807/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securitySchemeObject>.
808#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
809#[serde(tag = "type")]
810pub enum SecurityScheme {
811    #[serde(rename = "apiKey")]
812    ApiKey {
813        name: String,
814        #[serde(rename = "in")]
815        location: String,
816    },
817    #[serde(rename = "http")]
818    Http {
819        scheme: String,
820        #[serde(rename = "bearerFormat")]
821        bearer_format: String,
822    },
823    #[serde(rename = "oauth2")]
824    OAuth2 { flows: Box<Flows> },
825    #[serde(rename = "openIdConnect")]
826    OpenIdConnect {
827        #[serde(rename = "openIdConnectUrl")]
828        open_id_connect_url: String,
829    },
830}
831
832/// Allows configuration of the supported OAuth Flows.
833/// See [link]
834/// [link][https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauth-flows-object]
835#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
836#[serde(rename_all = "camelCase")]
837pub struct Flows {
838    #[serde(skip_serializing_if = "Option::is_none")]
839    pub implicit: Option<ImplicitFlow>,
840    #[serde(skip_serializing_if = "Option::is_none")]
841    pub password: Option<PasswordFlow>,
842    #[serde(skip_serializing_if = "Option::is_none")]
843    pub client_credentials: Option<ClientCredentialsFlow>,
844    #[serde(skip_serializing_if = "Option::is_none")]
845    pub authorization_code: Option<AuthorizationCodeFlow>,
846}
847
848/// Configuration details for a implicit OAuth Flow
849/// See [link]
850/// [link](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauth-flow-object)
851#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
852#[serde(rename_all = "camelCase")]
853pub struct ImplicitFlow {
854    pub authorization_url: Url,
855    #[serde(skip_serializing_if = "Option::is_none")]
856    pub refresh_url: Option<Url>,
857    pub scopes: IndexMap<String, String>,
858}
859
860/// Configuration details for a password OAuth Flow
861/// See [link]
862/// [link](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauth-flow-object
863#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
864#[serde(rename_all = "camelCase")]
865pub struct PasswordFlow {
866    token_url: Url,
867    #[serde(skip_serializing_if = "Option::is_none")]
868    pub refresh_url: Option<Url>,
869    pub scopes: IndexMap<String, String>,
870}
871
872/// Configuration details for a client credentials OAuth Flow
873/// See [link]
874/// [link](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauth-flow-object
875#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
876#[serde(rename_all = "camelCase")]
877pub struct ClientCredentialsFlow {
878    token_url: Url,
879    #[serde(skip_serializing_if = "Option::is_none")]
880    pub refresh_url: Option<Url>,
881    pub scopes: IndexMap<String, String>,
882}
883
884/// Configuration details for a authorization code OAuth Flow
885/// See [link]
886/// [link](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauth-flow-object
887#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
888#[serde(rename_all = "camelCase")]
889pub struct AuthorizationCodeFlow {
890    pub authorization_url: Url,
891    token_url: Url,
892    #[serde(skip_serializing_if = "Option::is_none")]
893    pub refresh_url: Option<Url>,
894    pub scopes: IndexMap<String, String>,
895}
896
897/// Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object.
898///
899/// Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
900///
901/// When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object, only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
902///
903/// See <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securityRequirementObject>.
904pub type SecurityRequirement = IndexMap<String, Vec<String>>;
jsona_openapi/openapi.rs

jsona_openapi/
openapi.rs
