jsapi 1.2 → 1.4

data/lib/jsapi/meta/operation.rb

@@ -28,18 +28,8 @@ module Jsapi
 
       ##
       # :attr: method
-      # The HTTP verb of the operation. Possible values are:
-      #
-      # - <code>"delete"</code>
-      # - <code>"get"</code>
-      # - <code>"head"</code>
-      # - <code>"options"</code>
-      # - <code>"patch"</code>
-      # - <code>"post"</code>
-      # - <code>"put"</code>
-      #
-      # The default HTTP verb is <code>"get"</code>.
-      attribute :method, values: %w[delete get head options patch post put], default: 'get'
+      # The HTTP method of the operation, <code>"get"</code> by default.
+      attribute :method, String, default: 'get'
 
       ##
       # :attr: model
@@ -56,10 +46,15 @@ module Jsapi
       # The parameters of the operation.
       attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
+      ##
+      # :attr_reader: parent_path
+      # The parent path as a Pathname.
+      attribute :parent_path, Pathname, accessors: %i[reader]
+
       ##
       # :attr: path
-      # The relative path of the operation.
-      attribute :path, String
+      # The relative path of the operation as a Pathname.
+      attribute :path, Pathname
 
       ##
       # :attr: request_body
@@ -97,7 +92,7 @@ module Jsapi
 
       ##
       # :attr: summary
-      # The short summary of the operation.
+      # The short description of the operation.
       attribute :summary, String
 
       ##
@@ -105,8 +100,11 @@ module Jsapi
       # The tags used to group operations in an \OpenAPI document.
       attribute :tags, [String]
 
-      def initialize(name = nil, keywords = {})
+      def initialize(name, parent_path = nil, keywords = {})
+        parent_path, keywords = nil, parent_path if parent_path.is_a?(Hash)
+
         @name = name&.to_s
+        @parent_path = Pathname.from(parent_path)
         super(keywords)
       end
 
@@ -114,6 +112,11 @@ module Jsapi
         (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
       end
 
+      # Returns the full path of the operation as a Pathname.
+      def full_path
+        parent_path + path
+      end
+
       # Returns the MIME type consumed by the operation.
       def consumes(definitions)
         request_body&.resolve(definitions)&.content_type
@@ -126,6 +129,13 @@ module Jsapi
         end.uniq.sort
       end
 
+      # Merges the parameters of this operation and the common parameters of all
+      # parent pathes and resolves them.
+      def resolved_parameters(definitions)
+        (definitions.path_parameters(full_path).presence&.merge(parameters) || parameters)
+          .transform_values { |parameter| parameter.resolve(definitions) }
+      end
+
       # Returns a hash representing the \OpenAPI operation object.
       def to_openapi(version, definitions)
         version = OpenAPI::Version.from(version)
@@ -148,7 +158,9 @@ module Jsapi
             end
             result[:schemes] = schemes if schemes.present?
           elsif servers.present?
-            result[:servers] = servers.map(&:to_openapi)
+            result[:servers] = servers.map do |server|
+              server.to_openapi(version)
+            end
           end
           # Parameters (and request body)
           result[:parameters] = parameters.values.flat_map do |parameter|

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/path.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a path.
+    class Path < Model::Base
+      ##
+      # :attr: description
+      # The description that applies to all operations in this path.
+      # Applies to \OpenAPI 3.0 and higher.
+      attribute :description, String
+
+      ##
+      # :attr_reader: name
+      # The relative path as a Pathname.
+      attribute :name, Pathname, accessors: %i[reader]
+
+      ##
+      # :attr: parameters
+      # The Parameter objects applicable for all operations in this path.
+      attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
+
+      ##
+      # :attr_reader: owner
+      attribute :owner, accessors: %i[reader]
+
+      ##
+      # :attr: summary
+      # The summary that applies to all operations in this path.
+      # Applies to \OpenAPI 3.0 and higher.
+      attribute :summary, String
+
+      ##
+      # :attr: servers
+      # The Server objects that applies to all operations in this path.
+      # Applies to \OpenAPI 3.0 and higher.
+      attribute :servers, [Server]
+
+      # Creates a new path with the given name and owner.
+      def initialize(name, owner, keywords = {})
+        @name = Pathname.from(name)
+        @owner = owner
+        super(keywords)
+      end
+
+      def add_parameter(name, keywords = {}) # :nodoc:
+        name = name.to_s
+
+        Parameter.new(name, keywords).tap do |parameter|
+          (@parameters ||= {})[name] = parameter
+          @owner.try(:invalidate_path_parameters, self.name)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/pathname.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Represents a relative path name.
+    class Pathname
+      class << self
+        # Creates a Pathname from +name+.
+        def from(name)
+          return name if name.is_a?(Pathname)
+
+          name.nil? ? new : new(name)
+        end
+      end
+
+      attr_reader :segments
+
+      delegate :hash, to: :segments
+
+      def initialize(*segments) # :nodoc:
+        @segments = segments.flat_map do |segment|
+          segment = segment.to_s.delete_prefix('/')
+          segment.present? ? segment.split('/', -1) : ''
+        end
+      end
+
+      def ==(other) # :nodoc:
+        other.is_a?(Pathname) && segments == other.segments
+      end
+
+      alias eql? ==
+
+      # Creates a new Pathname by appending +other+ to +self+.
+      # Returns +self+ if +other+ is nil.
+      def +(other)
+        return self if other.nil?
+
+        Pathname.new(*@segments, *Pathname.from(other).segments)
+      end
+
+      # Returns an array containing itself and all parent pathnames.
+      def ancestors
+        @ancestors ||= @segments.count.downto(0).map do |i|
+          Pathname.new(*@segments[0, i])
+        end
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class} #{to_s.inspect}>"
+      end
+
+      # Returns the relative path name as a string.
+      def to_s
+        @to_s ||= @segments.presence&.each_with_index&.map do |segment, index|
+          index.zero? && segment.blank? ? '//' : "/#{segment}"
+        end&.join || '/'
+      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