Support for OpenAPI v3.1

Cargo.toml

@@ -13,6 +13,7 @@ description = "This crate provides data structures that represent the OpenAPI v3
 serde = {version = "1.0", features = ["derive"]}
 serde_json = "1.0"
 indexmap = {version = "1.0", features = ["serde-1"]}
+schemars = "0.8.7"
 
 [dev-dependencies]
 newline-converter = "0.2.0"

README.md

@@ -1,7 +1,7 @@
 # OpenAPI v3 ![example workflow](https://github.com/glademiller/openapiv3/actions/workflows/rust.yml/badge.svg)
 
 
-This crate provides data structures that represent the [OpenAPI v3.0.x specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). Note this does not cover OpenAPI v3.1 which was an incompatible change.
+This crate provides data structures that represent the [OpenAPI v3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) and [OpenAPI v3.1.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) specifications.
 
 ## Example
 
@@ -38,4 +38,4 @@ This crate is licensed under either of
 
 ## Contribution
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

fixtures/non-oauth-scopes.yaml

@@ -0,0 +1,19 @@
+openapi: 3.1.0
+info:
+  title: Non-oAuth Scopes example
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      security:
+        - bearerAuth:
+            - 'read:users'
+            - 'public'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: jwt
+      description: 'note: non-oauth scopes are not defined at the securityScheme level'
+

fixtures/webhook-example.yaml

@@ -0,0 +1,34 @@
+openapi: 3.1.0
+info:
+  title: Webhook Example
+  version: 1.0.0
+# Since OAS 3.1.0 the paths element isn't necessary. Now a valid OpenAPI Document can describe only paths, webhooks, or even only reusable components
+webhooks:
+  # Each webhook needs a name
+  newPet:
+    # This is a Path Item Object, the only difference is that the request is initiated by the API provider
+    post:
+      requestBody:
+        description: Information about a new pet in the system
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        "200":
+          description: Return a 200 status to indicate that the data was received successfully
+
+components:
+  schemas:
+    Pet:
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string

src/lib.rs

@@ -1,57 +1,17 @@
-mod callback;
-mod components;
-mod contact;
-mod discriminator;
-mod encoding;
-mod example;
-mod external_documentation;
-mod header;
-mod info;
-mod license;
-mod link;
-mod media_type;
-mod openapi;
-mod operation;
-mod parameter;
-mod paths;
-mod reference;
-mod request_body;
-mod responses;
-mod schema;
-mod security_requirement;
-mod security_scheme;
-mod server;
-mod server_variable;
-mod status_code;
-mod tag;
 mod util;
-mod variant_or;
+pub mod v3_0;
+pub mod v3_1;
 
-pub use self::callback::*;
-pub use self::components::*;
-pub use self::contact::*;
-pub use self::discriminator::*;
-pub use self::encoding::*;
-pub use self::example::*;
-pub use self::external_documentation::*;
-pub use self::header::*;
-pub use self::info::*;
-pub use self::license::*;
-pub use self::link::*;
-pub use self::media_type::*;
-pub use self::openapi::*;
-pub use self::operation::*;
-pub use self::parameter::*;
-pub use self::paths::*;
-pub use self::reference::*;
-pub use self::request_body::*;
-pub use self::responses::*;
-pub use self::schema::*;
-pub use self::security_requirement::*;
-pub use self::security_scheme::*;
-pub use self::server::*;
-pub use self::server_variable::*;
-pub use self::status_code::*;
-pub use self::tag::*;
 pub use self::util::*;
-pub use self::variant_or::*;
+pub use schemars;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(tag = "openapi")]
+pub enum OpenAPI {
+    #[serde(rename = "3.0.0", alias = "3.0.1", alias = "3.0.2", alias = "3.0.3")]
+    Version30(v3_0::OpenAPI),
+    #[serde(rename = "3.1.0")]
+    Version31(v3_1::OpenAPI),
+}

src/callback.rs → src/v3_0/callback.rs

@@ -1,9 +1,10 @@
-use crate::*;
+use crate::v3_0::*;
 use indexmap::IndexMap;
 
 /// A map of possible out-of band callbacks related to the parent operation.
 /// Each value in the map is a Path Item Object that describes a set of
-/// requests that may be initiated by the API provider and the expected responses.
-/// The key value used to identify the callback object is an expression,
-/// evaluated at runtime, that identifies a URL to use for the callback operation.
+/// requests that may be initiated by the API provider and the expected
+/// responses. The key value used to identify the callback object is an
+/// expression, evaluated at runtime, that identifies a URL to use for the
+/// callback operation.
 pub type Callback = IndexMap<String, PathItem>;

src/components.rs → src/v3_0/components.rs

@@ -1,4 +1,4 @@
-use crate::*;
+use crate::v3_0::*;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 

src/discriminator.rs → src/v3_0/discriminator.rs

@@ -1,11 +1,11 @@
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
-/// When request bodies or response payloads may be one of a number of different schemas,
-/// a discriminator object can be used to aid in serialization, deserialization,
-/// and validation. The discriminator is a specific object in a schema which is
-/// used to inform the consumer of the specification of an alternative schema based
-/// on the value associated with it.
+/// When request bodies or response payloads may be one of a number of different
+/// schemas, a discriminator object can be used to aid in serialization,
+/// deserialization, and validation. The discriminator is a specific object in a
+/// schema which is used to inform the consumer of the specification of an
+/// alternative schema based on the value associated with it.
 ///
 /// When using the discriminator, inline schemas will not be considered.
 #[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
@@ -14,7 +14,8 @@ pub struct Discriminator {
     /// REQUIRED. The name of the property in the payload that
     /// will hold the discriminator value.
     pub property_name: String,
-    /// An object to hold mappings between payload values and schema names or references.
+    /// An object to hold mappings between payload values and schema names or
+    /// references.
     #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
     pub mapping: IndexMap<String, String>,
     /// Inline extensions to this object.

src/encoding.rs → src/v3_0/encoding.rs

@@ -1,4 +1,4 @@
-use crate::*;
+use crate::{util::*, v3_0::*};
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
@@ -13,7 +13,8 @@ pub struct Encoding {
     /// for object - application/json;
     /// for array – the default is defined based on the inner type.
     /// The value can be a specific media type (e.g. application/json),
-    /// a wildcard media type (e.g. image/*), or a comma-separated list of the two types.
+    /// a wildcard media type (e.g. image/*), or a comma-separated list of the
+    /// two types.
     pub content_type: Option<String>,
     /// A map allowing additional information to be provided as headers,
     /// for example Content-Disposition. Content-Type is described separately
@@ -36,13 +37,15 @@ pub struct Encoding {
     /// SHALL be ignored if the request body media type is
     /// not application/x-www-form-urlencoded.
     ///
-    /// In this Library this value defaults to false always despite the specification.
+    /// In this Library this value defaults to false always despite the
+    /// specification.
     #[serde(default, skip_serializing_if = "is_false")]
     pub explode: bool,
     /// Determines whether the parameter value SHOULD allow reserved characters,
-    /// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
-    /// The default value is false. This property SHALL be ignored if the request
-    /// body media type is not application/x-www-form-urlencoded.
+    /// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without
+    /// percent-encoding. The default value is false. This property SHALL be
+    /// ignored if the request body media type is not
+    /// application/x-www-form-urlencoded.
     #[serde(default, skip_serializing_if = "is_false")]
     pub allow_reserved: bool,
     /// Inline extensions to this object.

src/header.rs → src/v3_0/header.rs

@@ -1,12 +1,14 @@
-use crate::*;
+use crate::{util::*, v3_0::*};
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
-/// The Header Object follows the structure of the Parameter Object with the following changes:
+/// The Header Object follows the structure of the Parameter Object with the
+/// following changes:
 ///
 /// 1) name MUST NOT be specified, it is given in the corresponding headers map.
 /// 2) in MUST NOT be specified, it is implicitly in header.
-/// 3) All traits that are affected by the location MUST be applicable to a location of header (for example, style).
+/// 3) All traits that are affected by the location MUST be applicable to a
+/// location of header (for example, style).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct Header {

src/info.rs → src/v3_0/info.rs

@@ -1,10 +1,11 @@
-use crate::*;
+use crate::v3_0::*;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
 /// The object provides metadata about the API.
 /// The metadata MAY be used by the clients if needed,
-/// and MAY be presented in editing or documentation generation tools for convenience.
+/// and MAY be presented in editing or documentation generation tools for
+/// convenience.
 #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
 pub struct Info {
     /// REQUIRED. The title of the application.

src/link.rs → src/v3_0/link.rs

@@ -1,4 +1,4 @@
-use crate::*;
+use crate::v3_0::*;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
@@ -8,7 +8,8 @@ use serde::{Deserialize, Serialize};
 /// traversal mechanism between responses and other operations.
 ///
 /// Unlike dynamic links (i.e. links provided in the response payload),
-/// the OAS linking mechanism does not require link information in the runtime response.
+/// the OAS linking mechanism does not require link information in the runtime
+/// response.
 ///
 /// For computing links, and providing instructions to execute them,
 /// a runtime expression is used for accessing values in an operation

src/media_type.rs → src/v3_0/media_type.rs

@@ -1,4 +1,4 @@
-use crate::*;
+use crate::v3_0::*;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 

src/v3_0/mod.rs

@@ -0,0 +1,55 @@
+mod callback;
+mod components;
+mod contact;
+mod discriminator;
+mod encoding;
+mod example;
+mod external_documentation;
+mod header;
+mod info;
+mod license;
+mod link;
+mod media_type;
+mod openapi;
+mod operation;
+mod parameter;
+mod paths;
+mod reference;
+mod request_body;
+mod responses;
+mod schema;
+mod security_requirement;
+mod security_scheme;
+mod server;
+mod server_variable;
+mod status_code;
+mod tag;
+mod variant_or;
+
+pub use self::callback::*;
+pub use self::components::*;
+pub use self::contact::*;
+pub use self::discriminator::*;
+pub use self::encoding::*;
+pub use self::example::*;
+pub use self::external_documentation::*;
+pub use self::header::*;
+pub use self::info::*;
+pub use self::license::*;
+pub use self::link::*;
+pub use self::media_type::*;
+pub use self::openapi::*;
+pub use self::operation::*;
+pub use self::parameter::*;
+pub use self::paths::*;
+pub use self::reference::*;
+pub use self::request_body::*;
+pub use self::responses::*;
+pub use self::schema::*;
+pub use self::security_requirement::*;
+pub use self::security_scheme::*;
+pub use self::server::*;
+pub use self::server_variable::*;
+pub use self::status_code::*;
+pub use self::tag::*;
+pub use self::variant_or::*;

src/openapi.rs → src/v3_0/openapi.rs

@@ -1,15 +1,9 @@
-use crate::*;
+use crate::v3_0::*;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
 pub struct OpenAPI {
-    /// REQUIRED. This string MUST be the semantic version number of the
-    /// OpenAPI Specification version that the OpenAPI document uses.
-    /// The openapi field SHOULD be used by tooling specifications and
-    /// clients to interpret the OpenAPI document. This is not related to
-    /// the API info.version string.
-    pub openapi: String,
     /// REQUIRED. Provides metadata about the API.
     /// The metadata MAY be used by tooling as required.
     pub info: Info,
@@ -28,8 +22,8 @@ pub struct OpenAPI {
     /// The list of values includes alternative security requirement objects
     /// that can be used. Only one of the security requirement objects need to
     /// be satisfied to authorize a request. Individual operations can override
-    /// this definition. Global security settings may be overridden on a per-path
-    /// basis.
+    /// this definition. Global security settings may be overridden on a
+    /// per-path basis.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub security: Option<Vec<SecurityRequirement>>,