jsapi 1.1.1 → 1.3

data/lib/jsapi/meta/parameter/base.rb

@@ -9,6 +9,11 @@ module Jsapi
 
         delegate_missing_to :schema
 
+        ##
+        # :attr: content_type
+        # The content type used to describe complex parameters in \OpenAPI 3.0 and higher.
+        attribute :content_type, String
+
         ##
         # :attr: deprecated
         # Specifies whether or not the parameter is deprecated.
@@ -31,9 +36,10 @@ module Jsapi
         # - <code>"header"</code>
         # - <code>"path"</code>
         # - <code>"query"</code>
+        # - <code>"querystring"</code>
         #
         # The default location is <code>"query"</code>.
-        attribute :in, String, values: %w[header path query], default: 'query'
+        attribute :in, String, values: %w[header path query querystring], default: 'query'
 
         ##
         # :attr_reader: name
@@ -54,8 +60,16 @@ module Jsapi
           @name = name.to_s
 
           keywords = keywords.dup
-          super(keywords.extract!(:deprecated, :description, :examples, :in, :openapi_extensions))
-
+          super(
+            keywords.extract!(
+              :content_type,
+              :deprecated,
+              :description,
+              :examples,
+              :in,
+              :openapi_extensions
+            )
+          )
           add_example(value: keywords.delete(:example)) if keywords.key?(:example)
           keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
 
@@ -75,12 +89,13 @@ module Jsapi
         # Returns a hash representing the \OpenAPI parameter object.
         def to_openapi(version, definitions)
           version = OpenAPI::Version.from(version)
-          schema = self.schema.resolve(definitions)
 
-          openapi_parameter(
+          openapi_parameter_object(
             name,
-            schema,
+            schema.resolve(definitions),
             version,
+            location: self.in,
+            content_type: content_type || ('text/plain' if self.in == 'querystring'),
             description: description,
             required: required?,
             deprecated: deprecated?,
@@ -92,39 +107,30 @@ module Jsapi
         # Returns an array of hashes representing the \OpenAPI parameter objects.
         def to_openapi_parameters(version, definitions)
           version = OpenAPI::Version.from(version)
+          is_querystring = self.in == 'querystring'
           schema = self.schema.resolve(definitions)
 
-          if schema.object?
+          if schema.object? && (version < OpenAPI::V3_2 || !is_querystring)
             explode_parameter(
-              name,
+              is_querystring ? nil : name,
               schema,
               version,
               definitions,
+              location: is_querystring ? 'query' : self.in,
               required: required?,
               deprecated: deprecated?
             )
           else
-            [
-              openapi_parameter(
-                name,
-                schema,
-                version,
-                description: description,
-                required: required?,
-                deprecated: deprecated?,
-                allow_empty_value: allow_empty_value?,
-                examples: examples
-              )
-            ]
-          end
+            [to_openapi(version, definitions)]
+          end.compact
         end
 
         private
 
-        def explode_parameter(name, schema, version, definitions, required:, deprecated:)
+        def explode_parameter(name, schema, version, definitions, location:, required:, deprecated:)
           schema.resolve_properties(definitions, context: :request).values.flat_map do |property|
             property_schema = property.schema.resolve(definitions)
-            parameter_name = "#{name}[#{property.name}]"
+            parameter_name = name ? "#{name}[#{property.name}]" : property.name
             required = (required && property.required?).presence
             deprecated = (deprecated || property_schema.deprecated?).presence
 
@@ -134,62 +140,79 @@ module Jsapi
                 property_schema,
                 version,
                 definitions,
+                location: location,
                 required: required,
                 deprecated: deprecated
               )
             else
               [
-                openapi_parameter(
+                openapi_parameter_object(
                   parameter_name,
                   property_schema,
                   version,
+                  location: location,
                   description: property_schema.description,
                   required: required,
                   deprecated: deprecated,
                   allow_empty_value: property.schema.existence <= Existence::ALLOW_EMPTY
                 )
               ]
-            end
+            end.compact
           end
         end
 
-        def openapi_parameter(name, schema, version,
-                              allow_empty_value:,
-                              deprecated:,
-                              description:,
-                              required:,
-                              examples: nil)
+        def openapi_parameter_object(name, schema, version,
+                                     allow_empty_value:,
+                                     deprecated:,
+                                     description:,
+                                     location:,
+                                     required:,
+                                     content_type: nil,
+                                     examples: nil)
 
-          name = schema.array? ? "#{name}[]" : name
+          return if location == 'querystring' && version < OpenAPI::V3_2
+
+          if schema.object? && version == OpenAPI::V2_0
+            raise "OpenAPI 2.0 doesn't allow object parameters in #{location}"
+          end
+
+          name = "#{name}[]" if schema.array?
 
           with_openapi_extensions(
-            if version.major == 2
-              raise "OpenAPI 2.0 doesn't allow object parameters " \
-                    "in #{self.in}" if schema.object?
-
-              {
-                name: name,
-                in: self.in,
-                description: description,
-                required: required.presence,
-                allowEmptyValue: allow_empty_value.presence,
-                collectionFormat: ('multi' if schema.array?)
-              }.merge(schema.to_openapi(version))
-            else
-              {
-                name: name,
-                in: self.in,
-                description: description,
-                required: required.presence,
-                allowEmptyValue: allow_empty_value.presence,
-                deprecated: deprecated.presence,
-                schema: schema.to_openapi(version).except(:deprecated),
-                examples: examples&.transform_values(&:to_openapi).presence
-
-                # NOTE: collectionFormat is replaced by 'style' and 'explode'.
-                #       The default values are equal to 'multi'.
-              }
-            end
+            name: name,
+            in: location,
+            description: description,
+            required: required.presence,
+            allowEmptyValue: allow_empty_value.presence,
+            **if version == OpenAPI::V2_0
+                {
+                  collectionFormat: ('multi' if schema.array?),
+                  **schema.to_openapi(version)
+                }
+              else
+                openapi_schema = schema.to_openapi(version).except(:deprecated)
+                openapi_examples = examples&.transform_values(&:to_openapi).presence
+                {
+                  deprecated: deprecated.presence,
+                  **if content_type.blank?
+                      # simple scenario
+                      {
+                        schema: openapi_schema,
+                        examples: openapi_examples
+                      }
+                    else
+                      # complex scenario
+                      {
+                        content: {
+                          content_type => {
+                            schema: openapi_schema,
+                            examples: openapi_examples
+                          }.compact
+                        }
+                      }
+                    end
+                }
+              end
           )
         end
       end

data/lib/jsapi/meta/request_body/base.rb

@@ -52,8 +52,9 @@ module Jsapi
               name: 'body',
               in: 'body',
               description: description,
-              required: required?
-            }.merge(schema.to_openapi(OpenAPI::V2_0))
+              required: required?,
+              **schema.to_openapi(OpenAPI::V2_0)
+            }
           )
         end
 

data/lib/jsapi/meta/response/base.rb

@@ -8,12 +8,13 @@ module Jsapi
         include OpenAPI::Extensions
 
         JSON_TYPE = %r{(^application/|^text/|\+)json$}.freeze # :nodoc:
+        JSON_SEQ_TYPE = 'application/json-seq' # :nodoc:
 
         delegate_missing_to :schema
 
         ##
         # :attr: content_type
-        # The content type. <code>"application/json"</code> by default.
+        # The content type, <code>"application/json"</code> by default.
         attribute :content_type, String, default: 'application/json'
 
         ##
@@ -46,12 +47,17 @@ module Jsapi
         # The Schema of the response.
         attribute :schema, accessors: %i[reader]
 
+        ##
+        # :attr: summary
+        # The short description of the response. Applies to \OpenAPI 3.2 and higher.
+        attribute :summary, String
+
         def initialize(keywords = {})
           keywords = keywords.dup
           super(
             keywords.extract!(
               :content_type, :description, :examples, :headers,
-              :links, :locale, :openapi_extensions
+              :links, :locale, :openapi_extensions, :summary
             )
           )
           add_example(value: keywords.delete(:example)) if keywords.key?(:example)
@@ -66,12 +72,17 @@ module Jsapi
           content_type.match?(JSON_TYPE)
         end
 
+        # Returns true if content type is <code>"application/json-seq"</code>.
+        def json_seq_type?
+          content_type == JSON_SEQ_TYPE
+        end
+
         # Returns a hash representing the \OpenAPI response object.
         def to_openapi(version, definitions)
           version = OpenAPI::Version.from(version)
 
           with_openapi_extensions(
-            if version.major == 2
+            if version == OpenAPI::V2_0
               {
                 description: description,
                 schema: schema.to_openapi(version),
@@ -86,17 +97,24 @@ module Jsapi
               }
             else
               {
+                summary: (summary if version >= OpenAPI::V3_2),
                 description: description,
+                headers: headers.transform_values do |header|
+                  header.to_openapi(version)
+                end.presence,
                 content: {
                   content_type => {
-                    schema: schema.to_openapi(version),
+                    **if json_seq_type? && schema.array? && version >= OpenAPI::V3_2
+                        { itemSchema: schema.items.to_openapi(version) }
+                      else
+                        { schema: schema.to_openapi(version) }
+                      end,
                     examples: examples.transform_values(&:to_openapi).presence
                   }.compact
                 },
-                headers: headers.transform_values do |header|
-                  header.to_openapi(version)
-                end.presence,
-                links: links.transform_values(&:to_openapi).presence
+                links: links.transform_values do |link|
+                  link.to_openapi(version)
+                end.presence
               }
             end
           )

data/lib/jsapi/meta/schema/base.rb

@@ -121,7 +121,7 @@ module Jsapi
                 deprecated: deprecated?.presence
               }
             else
-              # OpenAPI 3.1
+              # OpenAPI 3.1 and higher
               {
                 type: nullable? ? [type, 'null'] : type,
                 examples: examples.presence,

data/lib/jsapi/meta/schema/discriminator.rb

@@ -4,8 +4,16 @@ module Jsapi
   module Meta
     module Schema
       class Discriminator < Model::Base
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: default_mapping
+        # Applies to \OpenAPI 3.2 and higher.
+        attribute :default_mapping, String
+
         ##
         # :attr: mappings
+        # Applies to \OpenAPI 3.0 and higher.
         attribute :mappings, { Object => String }
 
         ##
@@ -15,12 +23,14 @@ module Jsapi
         # Returns a hash representing the \OpenAPI discriminator object.
         def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
-          return property_name if version.major == 2
+          return property_name if version < OpenAPI::V3_0
 
-          {
+          result = {
             propertyName: property_name,
-            mapping: mappings.transform_keys(&:to_s).presence
-          }.compact
+            mapping: mappings.transform_keys(&:to_s).presence,
+            defaultMapping: (default_mapping if version >= OpenAPI::V3_2)
+          }
+          version >= OpenAPI::V3_1 ? with_openapi_extensions(result) : result.compact
         end
       end
     end

data/lib/jsapi/meta/schema/object.rb

@@ -57,17 +57,36 @@ module Jsapi
 
           properties = resolve_properties(definitions, context: context)
 
-          property = properties[discriminator.property_name]
-          raise InvalidValueError.new('discriminator property',
-                                      discriminator.property_name,
-                                      valid_values: properties.keys) if property.nil?
+          discriminating_property = properties[discriminator.property_name]
+          if discriminating_property.nil?
+            raise InvalidValueError.new('discriminator property',
+                                        discriminator.property_name,
+                                        valid_values: properties.keys)
+          end
+
+          discriminating_value = discriminating_property.reader.call(object)
+          if discriminating_value.nil?
+            discriminating_value = discriminating_property.default_value(
+              definitions,
+              context: context
+            )
+            if discriminating_value.nil? && discriminator.default_mapping.nil?
+              raise "discriminating value can't be nil"
+            end
+          end
 
-          value = property.reader.call(object)
-          value = property.default_value(definitions, context: context) if value.nil?
-          raise "#{discriminator.property_name} can't be nil" if value.nil?
+          schema_name = discriminator.mapping(discriminating_value) || discriminating_value
 
-          schema = definitions.find_schema(discriminator.mapping(value) || value)
-          raise "inheriting schema couldn't be found: #{value.inspect}" if schema.nil?
+          schema = definitions.find_schema(schema_name)
+          if schema.nil?
+            default_mapping = discriminator.default_mapping
+            schema = definitions.find_schema(default_mapping) unless default_mapping.nil?
+
+            if schema.nil?
+              raise "inheriting schema couldn't be found: " \
+                    "#{[schema_name, default_mapping].compact.map(&:inspect).join(' or ')}"
+            end
+          end
 
           schema.resolve(definitions).resolve_schema(object, definitions, context: context)
         end

data/lib/jsapi/meta/schema/validation/maximum.rb

@@ -43,7 +43,7 @@ module Jsapi
 
           def to_openapi_validation(version)
             version = OpenAPI::Version.from(version)
-            return to_json_schema_validation if version.major == 3 && version.minor == 1
+            return to_json_schema_validation if version >= OpenAPI::V3_1
             return super unless exclusive
 
             { maximum: value, exclusiveMaximum: true }

data/lib/jsapi/meta/schema/validation/minimum.rb

@@ -43,7 +43,7 @@ module Jsapi
 
           def to_openapi_validation(version)
             version = OpenAPI::Version.from(version)
-            return to_json_schema_validation if version.major == 3 && version.minor == 1
+            return to_json_schema_validation if version >= OpenAPI::V3_1
             return super unless exclusive
 
             { minimum: value, exclusiveMinimum: true }

data/lib/jsapi/meta/security_scheme/api_key.rb

@@ -24,12 +24,11 @@ module Jsapi
         attribute :name, String
 
         # Returns a hash representing the \OpenAPI security scheme object.
-        def to_openapi(*)
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
           with_openapi_extensions(
-            type: 'apiKey',
-            name: name,
-            in: self.in,
-            description: description
+            base_openapi_fields('apiKey', version).merge(name: name, in: self.in)
           )
         end
       end

data/lib/jsapi/meta/security_scheme/base.rb

@@ -8,6 +8,22 @@ module Jsapi
         # :attr: description
         # The description of the security scheme.
         attribute :description, String
+
+        ##
+        # :attr: deprecated
+        # Specifies whether or not the security scheme is deprecated.
+        # Applies to \OpenAPI 3.2 and higher.
+        attribute :deprecated, values: [true, false]
+
+        private
+
+        def base_openapi_fields(type, version)
+          {
+            type: type,
+            description: description,
+            deprecated: (deprecated?.presence if version >= OpenAPI::V3_2)
+          }
+        end
       end
     end
   end

data/lib/jsapi/meta/security_scheme/http/basic.rb

@@ -13,17 +13,10 @@ module Jsapi
             version = OpenAPI::Version.from(version)
 
             with_openapi_extensions(
-              if version.major == 2
-                {
-                  type: 'basic',
-                  description: description
-                }
+              if version < OpenAPI::V3_0
+                base_openapi_fields('basic', version)
               else
-                {
-                  type: 'http',
-                  scheme: 'basic',
-                  description: description
-                }
+                base_openapi_fields('http', version).merge(scheme: 'basic')
               end
             )
           end

data/lib/jsapi/meta/security_scheme/http/bearer.rb

@@ -7,7 +7,7 @@ module Jsapi
         # Specifies a security scheme based on bearer authentication.
         #
         # Note that Bearer authentication was introduced with \OpenAPI 3.0. Thus, a security
-        # scheme of this class is skipped when generating an \OpenAPI 2.0 document.
+        # scheme of this class is omitted when generating an \OpenAPI 2.0 document.
         class Bearer < Base
           include OpenAPI::Extensions
 
@@ -16,17 +16,17 @@ module Jsapi
           # The format of the bearer token.
           attribute :bearer_format, String
 
-          # Returns a hash representing the \OpenAPI security scheme object, or
-          # +nil+ if <code>version.major</code> is 2.
+          # Returns a hash representing the \OpenAPI security scheme object, or +nil+
+          # if <code>version</code> is less than \OpenAPI 3.0.
           def to_openapi(version, *)
             version = OpenAPI::Version.from(version)
-            return if version.major == 2
+            return if version < OpenAPI::V3_0
 
             with_openapi_extensions(
-              type: 'http',
-              scheme: 'bearer',
-              bearerFormat: bearer_format,
-              description: description
+              base_openapi_fields('http', version).merge(
+                scheme: 'bearer',
+                bearerFormat: bearer_format
+              )
             )
           end
         end

data/lib/jsapi/meta/security_scheme/http/other.rb

@@ -18,15 +18,13 @@ module Jsapi
           attribute :scheme, String
 
           # Returns a hash representing the \OpenAPI security scheme object, or +nil+
-          # if <code>version.major</code> is 2.
+          # if <code>version</code> is less than \OpenAPI 3.0.
           def to_openapi(version, *)
             version = OpenAPI::Version.from(version)
-            return if version.major == 2
+            return if version < OpenAPI::V3_0
 
             with_openapi_extensions(
-              type: 'http',
-              scheme: scheme,
-              description: description
+              base_openapi_fields('http', version).merge(scheme: scheme)
             )
           end
         end

data/lib/jsapi/meta/security_scheme/mutual_tls.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      # Specifies a security scheme based on MutualTLS.
+      class MutualTLS < Base
+        include OpenAPI::Extensions
+
+        # Returns a hash representing the \OpenAPI security scheme object, or +nil+
+        # if <code>version</code> is less than \OpenAPI 3.1.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+          return if version < OpenAPI::V3_1
+
+          with_openapi_extensions(
+            base_openapi_fields('mutualTLS', version)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/oauth2.rb

@@ -9,34 +9,50 @@ module Jsapi
 
         ##
         # :attr: oauth_flows
-        # The hash containing the OAuth flows. Possible keys are:
+        # Maps one or more of the following keys to OAuthFlow objects.
         #
         # - <code>"authorization_code"</code>
         # - <code>"client_credentials"</code>
+        # - <code>"device_authorization"</code>
         # - <code>"implicit"</code>
         # - <code>"password"</code>
         #
-        # Values are OAuthFlow objects.
+        # Note that <code>"device_authorization"</code> was introduced with \OpenAPI 3.2.
+        # This entry is omitted when generating an \OpenAPI document with a lower version.
         attribute :oauth_flows, { String => OAuthFlow },
-                  keys: %w[authorization_code client_credentials implicit password]
+                  keys: %w[authorization_code
+                           client_credentials
+                           device_authorization
+                           implicit
+                           password]
+        ##
+        # :attr: oauth2_metadata_url
+        # The URL of the OAuth2 authorization server metadata.
+        # Applies to \OpenAPI 3.2 and higher.
+        attribute :oauth2_metadata_url, String
 
         # Returns a hash representing the \OpenAPI security scheme object.
         def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
 
-          with_openapi_extensions(type: 'oauth2', description: description).tap do |h|
-            if oauth_flows.any?
-              if version.major == 2
-                key, oauth_flow = oauth_flows.first
-                h[:flow] = key.to_s
-                h.merge!(oauth_flow.to_openapi(version))
-              else
-                h[:flows] = oauth_flows.to_h do |key, value|
+          with_openapi_extensions(
+            base_openapi_fields('oauth2', version).tap do |fields|
+              flows = oauth_flows
+              flows = flows.except('device_authorization') unless version >= OpenAPI::V3_2
+
+              if version >= OpenAPI::V3_0
+                fields[:flows] = flows.to_h do |key, value|
                   [key.to_s.camelize(:lower).to_sym, value.to_openapi(version)]
-                end
+                end if flows.any?
+
+                fields[:oauth2MetadataUrl] = oauth2_metadata_url if version >= OpenAPI::V3_2
+              elsif flows.one?
+                key, flow = flows.first
+                fields[:flow] = key.to_s
+                fields.merge!(flow.to_openapi(version))
               end
             end
-          end
+          )
         end
       end
     end