openapi_first 3.4.3 → 4.0.0

data/lib/openapi_first/middlewares/response_validation.rb

@@ -20,7 +20,7 @@ module OpenapiFirst
           options = spec
           spec = options[:spec]
         end
-        @raise = options.fetch(:raise_error, OpenapiFirst.configuration.response_validation_raise_error)
+        @raise = options.fetch(:raise_error, true)
 
         spec ||= :default
         spec = OpenapiFirst[spec] if spec.is_a?(Symbol)

data/lib/openapi_first/parameter/converter/array_converter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Parameter
+    module Converter
+      # Converts the items of an array parameter value
+      # @visibility private
+      ArrayConverter = Data.define(:schema) do
+        def call(value)
+          return [] if value.nil? || value.empty?
+
+          convert_array(value)
+        end
+
+        private
+
+        def convert_array(array)
+          return array unless array.is_a?(Array)
+
+          item_schema = schema['items']
+          prefix_schemas = schema['prefixItems']
+          return convert_array_with_prefixes(array, prefix_schemas, item_schema) if prefix_schemas
+
+          array.map { Converter.convert(_1, item_schema) }
+        end
+
+        def convert_array_with_prefixes(array, prefix_schemas, item_schema)
+          prefixes =
+            array
+            .slice(0, prefix_schemas.size)
+            .each_with_index
+            .map { |item, index| Converter.convert(item, prefix_schemas[index]) }
+          array =
+            array[prefix_schemas.size..].map! do |item|
+              Converter.convert(item, item_schema)
+            end
+          prefixes + array
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/parameter/converter/object_converter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Parameter
+    module Converter
+      # Converts the properties of an object parameter value
+      # @visibility private
+      ObjectConverter = Data.define(:schema) do
+        def self.get_properties(schema) # rubocop:disable Metrics
+          return nil if schema.nil? || schema.empty?
+
+          direct_props = schema['properties']
+          additional_props = schema['additionalProperties']
+
+          composition_props = []
+
+          %w[allOf oneOf anyOf].each do |keyword|
+            next unless (array = schema[keyword])
+
+            array.each do |sub_schema|
+              if (props = sub_schema['properties'])
+                composition_props << props
+              end
+            end
+          end
+
+          %w[then else].each do |keyword|
+            next unless (sub_schema = schema[keyword])
+
+            if (props = sub_schema['properties'])
+              composition_props << props
+            end
+            if (add_props = sub_schema['additionalProperties']) && add_props.is_a?(Hash) && !add_props.empty?
+              composition_props << add_props
+            end
+          end
+
+          composition_props << additional_props if additional_props.is_a?(Hash) && !additional_props.empty?
+
+          return direct_props if composition_props.empty? && direct_props
+          return nil if direct_props.nil? && composition_props.empty?
+
+          result = direct_props ? direct_props.dup : {}
+          composition_props.each { result.merge!(_1) }
+          result
+        end
+
+        def call(value)
+          return value unless value.is_a?(Hash)
+
+          properties = self.class.get_properties(schema)
+
+          value.each_with_object({}) do |(key, val), hsh|
+            hsh[key] = Converter.convert(val, properties&.fetch(key, nil))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/parameter/converter.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'converter/array_converter'
+require_relative 'converter/object_converter'
+
+module OpenapiFirst
+  class Parameter
+    # Converts a parameter value (string) to the type specified in the JSON Schema.
+    # @visibility private
+    module Converter
+      PASS_THROUGH = ->(value) { value }
+
+      INTEGER = lambda do |value|
+        Integer(value, 10)
+      rescue StandardError
+        value
+      end
+
+      NUMBER = lambda do |value|
+        Float(value)
+      rescue StandardError
+        value
+      end
+
+      BOOLEAN = lambda do |value|
+        if value == 'true'
+          true
+        else
+          value == 'false' ? false : value
+        end
+      end
+
+      class << self
+        # Returns a callable that converts a value as described in the schema
+        # @param schema [Hash, nil]
+        def [](schema)
+          case schema && schema['type']
+          when 'integer' then INTEGER
+          when 'number' then NUMBER
+          when 'boolean' then BOOLEAN
+          when 'object' then ObjectConverter.new(schema)
+          when 'array' then ArrayConverter.new(schema)
+          else
+            return ObjectConverter.new(schema) if object_like?(schema)
+
+            PASS_THROUGH
+          end
+        end
+
+        # Converts a nested value, like an array item or an object property
+        def convert(value, schema)
+          return if value.nil?
+          return value if schema.nil?
+
+          self[schema].call(value)
+        end
+
+        private
+
+        OBJECT_KEYWORDS = %w[properties oneOf allOf anyOf].freeze
+        private_constant :OBJECT_KEYWORDS
+
+        def object_like?(schema)
+          schema && OBJECT_KEYWORDS.any? { schema[_1] }
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/parameter/unpackers.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'rack'
+require_relative '../parameter_content_parsers'
+
+module OpenapiFirst
+  class Parameter
+    # Resolves the unpacker of a parameter once, at Parameter construction time.
+    # Each unpacker is a callable that takes a raw string (or already-parsed
+    # value) and returns the unpacked Ruby value, throwing :skip on unrecoverable
+    # parse errors.
+    # @visibility private
+    module Unpackers
+      ARRAY_DELIMITER = {
+        'label' => '.',
+        'simple' => ',',
+        'form' => ',',
+        'pipeDelimited' => '|',
+        'spaceDelimited' => ' '
+      }.freeze
+      private_constant :ARRAY_DELIMITER
+
+      PREFIXED_STYLES = %w[label matrix].freeze
+      private_constant :PREFIXED_STYLES
+
+      OBJECT_EXPLODE_SPLITTER = Regexp.union(',', '=').freeze
+      private_constant :OBJECT_EXPLODE_SPLITTER
+
+      PassThrough = ->(value) { value }
+
+      DelimitedArray = Data.define(:delimiter, :strip_prefix) do
+        def call(value)
+          return value if value.is_a?(::Array)
+          return value if value.empty?
+
+          value = value[1..] if strip_prefix
+          value.split(delimiter)
+        end
+      end
+
+      MatrixArray = Data.define(:name, :explode) do
+        def call(value)
+          return value if value.is_a?(::Array)
+          return value if value.empty?
+
+          result = Unpackers.parse_query(value, ';')[name]
+          return result if explode
+          return result unless result.is_a?(::String)
+
+          result.split(',')
+        end
+      end
+
+      ExplodeFormObject = lambda do |value|
+        throw :skip, value unless value.is_a?(::String)
+
+        entries = value.split(OBJECT_EXPLODE_SPLITTER)
+        throw :skip, value if entries.length.odd?
+
+        Hash[*entries]
+      end
+
+      DelimitedObject = Data.define(:delimiter) do
+        def call(value)
+          throw :skip, value unless value.is_a?(::String)
+
+          entries = value.split(delimiter)
+          throw :skip, value if entries.length.odd?
+
+          Hash[*entries]
+        end
+      end
+
+      ExplodePathObject = ->(value) { Unpackers.parse_query(value, ',') }
+
+      NonExplodePathObject = Data.define(:array_unpacker) do
+        def call(value)
+          array = array_unpacker.call(value)
+          throw :skip, value if array.length.odd?
+
+          Hash[*array]
+        end
+      end
+
+      class << self
+        # Values that are not encoded as described are left to schema validation
+        def parse_query(value, delimiter)
+          Rack::Utils.parse_query(value, delimiter)
+        rescue ArgumentError
+          throw :skip, value
+        end
+
+        def find(parameter)
+          return find_media_type(parameter) if parameter.media_type
+          return find_array(parameter) if parameter.array?
+          return find_object(parameter) if parameter.object?
+
+          PassThrough
+        end
+
+        private
+
+        def find_media_type(parameter)
+          ParameterContentParsers[parameter.media_type] || PassThrough
+        end
+
+        def find_array(parameter)
+          style = parameter.style
+          return MatrixArray.new(name: parameter.name, explode: parameter.explode?) if style == 'matrix'
+
+          DelimitedArray.new(
+            delimiter: ARRAY_DELIMITER[style],
+            strip_prefix: PREFIXED_STYLES.include?(style)
+          )
+        end
+
+        def find_object(parameter)
+          return find_path_object(parameter) if parameter.location == 'path'
+          return ExplodeFormObject if parameter.explode?
+
+          DelimitedObject.new(delimiter: ARRAY_DELIMITER[parameter.style])
+        end
+
+        def find_path_object(parameter)
+          return ExplodePathObject if parameter.explode?
+
+          NonExplodePathObject.new(array_unpacker: find_array(parameter))
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/parameter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'parameter/converter'
+require_relative 'parameter/unpackers'
+
+module OpenapiFirst
+  # A parameter of a request, or a header of a response.
+  class Parameter
+    DEFAULT_STYLE = {
+      'query' => 'form',
+      'path' => 'simple',
+      'header' => 'simple',
+      'cookie' => 'form'
+    }.freeze
+    private_constant :DEFAULT_STYLE
+
+    # @param definition [Hash] The OpenAPI Parameter Object. A string keyed Hash.
+    # @param schema [Hash, nil] The resolved JSON Schema of this parameter.
+    def initialize(definition, schema:)
+      @name = definition['name']
+      @schema = schema
+      @location = definition['in']
+      @media_type = definition['content']&.keys&.first
+      @style = definition['style'] || DEFAULT_STYLE.fetch(@location)
+      @explode = definition.fetch('explode') { @style == 'form' }
+      @deep_object = @style == 'deepObject'
+      @required = @location == 'path' || definition['required'] == true
+      @deprecated = definition['deprecated'] == true
+      @converter = Converter[schema]
+      @unpacker = Unpackers.find(self)
+    end
+
+    attr_reader :name, :schema, :location, :media_type, :style
+
+    def unpack(value)
+      return value if value.nil?
+
+      @unpacker.call(value)
+    end
+
+    def convert(value) = @converter.call(value)
+
+    # Unpacks and converts a raw value.
+    # For a query parameter, a value that cannot be unpacked is still converted.
+    # For any other location, such a value is returned as it is, unconverted.
+    def unpack_and_convert(value)
+      return convert(catch(:skip) { unpack(value) }) if location == 'query'
+
+      catch(:skip) { convert(unpack(value)) }
+    end
+
+    def explode? = @explode
+
+    def required? = @required
+
+    def deprecated? = @deprecated
+
+    def deep_object? = @deep_object
+
+    def type = schema && schema['type']
+
+    def array? = type == 'array'
+
+    def object? = type == 'object' || deep_object? || schema&.key?('properties')
+
+    # The properties of an object parameter, merged across composition keywords.
+    # @return [Hash, nil]
+    def object_properties = Converter::ObjectConverter.get_properties(schema)
+  end
+end

data/lib/openapi_first/parameter_content_parsers.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module OpenapiFirst
+  # Registry of parsers for parameters that use a `content` field, keyed by media type.
+  #
+  # A parser is a callable that takes a raw string and returns the parsed value.
+  # It should `throw :skip, value` if the input cannot be parsed, so the
+  # parameter value is used as is.
+  #
+  #   OpenapiFirst::ParameterContentParsers.register('application/xml', ->(value) { ... })
+  module ParameterContentParsers
+    @parsers = []
+
+    class << self
+      attr_reader :parsers
+
+      # @param matcher [String, Regexp] exact media type or a pattern.
+      # @param parser [#call] callable that takes the raw string and returns the parsed value.
+      def register(matcher, parser)
+        parsers.reject! { |existing, _| existing == matcher }
+        parsers << [matcher, parser]
+      end
+
+      # @param media_type [String, nil]
+      # @return [#call, nil] the parser, or nil if none is registered.
+      def [](media_type)
+        return nil if media_type.nil?
+
+        parsers.each do |matcher, parser|
+          return parser if match?(matcher, media_type)
+        end
+        nil
+      end
+
+      private
+
+      def match?(matcher, media_type)
+        case matcher
+        when Regexp then matcher.match?(media_type)
+        else matcher == media_type
+        end
+      end
+    end
+
+    register(%r{\A[\w.+-]+/(?:[\w.-]+\+)?json\z}i, lambda do |value|
+      throw :skip, value unless value.is_a?(String)
+
+      JSON.parse(value)
+    rescue JSON::ParserError
+      throw :skip, value
+    end)
+  end
+end

data/lib/openapi_first/parameters_parser.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # Unpacks parameters from a Hash of raw values, like path parameters, headers or cookies.
+  # @visibility private
+  class ParametersParser
+    # @param parameters [Array<Parameter>]
+    def initialize(parameters)
+      @parameters = parameters
+    end
+
+    attr_reader :parameters
+
+    # @param parameters_hash [Hash] The raw values, keyed by parameter name.
+    def unpack(parameters_hash)
+      parameters.each_with_object({}) do |parameter, result|
+        next unless parameters_hash.key?(parameter.name)
+
+        result[parameter.name] = parameter.unpack_and_convert(parameters_hash[parameter.name])
+      end
+    end
+  end
+end

data/lib/openapi_first/query_string_parser.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'rack'
+require_relative 'parameters_parser'
+
+module OpenapiFirst
+  # Unpacks query parameters from a query string.
+  # @visibility private
+  class QueryStringParser
+    DEEP_PROP = '\[([\w-]+)\]$'
+    private_constant :DEEP_PROP
+
+    # @param parameters [Array<Parameter>]
+    def initialize(parameters)
+      @parameters = parameters
+      @deep_object_parameters, flat_parameters = parameters.partition(&:deep_object?)
+      @flat_parser = ParametersParser.new(flat_parameters)
+      @deep_object_properties = {}
+      @deep_object_regex = {}
+      @deep_object_parameters.each do |parameter|
+        @deep_object_properties[parameter.name] = parameter.object_properties
+        @deep_object_regex[parameter.name] = /^#{Regexp.escape(parameter.name)}#{DEEP_PROP}/
+      end
+    end
+
+    attr_reader :parameters
+
+    def unpack(query_string)
+      parsed_query = parse_query(query_string)
+      result = @flat_parser.unpack(parsed_query)
+      @deep_object_parameters.each do |parameter|
+        name = parameter.name
+        if parsed_query.key?(name)
+          result[name] = parameter.convert(parsed_query[name])
+        else
+          value = parse_deep_object(parameter, parsed_query)
+          result[name] = parameter.convert(value) unless value.empty?
+        end
+      end
+      result
+    end
+
+    # Returns query parameters that are not defined in the API description
+    def unknown_values(query_string)
+      parsed_query = parse_query(query_string)
+      known_parameter_names = parameters.to_set(&:name)
+
+      unknown = parsed_query.each_with_object({}) do |(key, value), result|
+        next if known_parameter_names.include?(key)
+        next if @deep_object_parameters.any? { key.start_with?("#{_1.name}[") }
+
+        result[key] = value
+      end
+      return if unknown.empty?
+
+      unknown
+    end
+
+    private
+
+    def parse_query(query_string)
+      Rack::Utils.parse_query(query_string) do |string|
+        Rack::Utils.unescape(string)
+      rescue ArgumentError => e
+        raise Rack::Utils::InvalidParameterError, e.message
+      end
+    end
+
+    def parse_deep_object(parameter, parsed_query)
+      name = parameter.name
+      prop_regx = @deep_object_regex[name]
+      properties_schema = @deep_object_properties[name]
+
+      parsed_query.each.with_object({}) do |(key, value), result|
+        prop_key = key.match(prop_regx)&.[](1)
+        next if prop_key.nil?
+
+        is_array = properties_schema&.dig(prop_key, 'type') == 'array'
+        result[prop_key] = explode_value(value, parameter, is_array)
+      end
+    end
+
+    def explode_value(value, parameter, is_array)
+      value = Array(value)
+      if is_array
+        return value if parameter.explode?
+
+        return [value.last]
+      end
+      value.last
+    end
+  end
+end

data/lib/openapi_first/ref_resolver.rb

@@ -84,7 +84,7 @@ module OpenapiFirst
       def resolve_ref(pointer)
         if pointer.start_with?('#')
           value = Hana::Pointer.new(pointer[1..]).eval(context)
-          raise "Unknown reference #{pointer} in #{context}" unless value
+          raise "Unknown reference #{pointer.inspect} in #{filepath || context}" unless value
 
           return ref_resolver.for(value, filepath:, context:)
         end
@@ -93,12 +93,19 @@ module OpenapiFirst
         full_path = File.expand_path(relative_path, dir)
         return ref_resolver.load(full_path) unless file_pointer
 
-        ref_resolver.file_at(full_path, file_pointer)
+        resolved = ref_resolver.file_at(full_path, file_pointer)
+        raise "Unknown reference #{pointer.inspect} in #{filepath || context}" unless resolved
+
+        resolved
       rescue OpenapiFirst::FileNotFoundError => e
         message = "Problem with reference resolving #{pointer.inspect} in " \
                   "file #{File.absolute_path(filepath).inspect}: #{e.message}"
         raise OpenapiFirst::FileNotFoundError, message
       end
+
+      private
+
+      def mark(visited) = (visited || []) + [value.object_id]
     end
 
     # @visibility private
@@ -106,6 +113,8 @@ module OpenapiFirst
       include Resolvable
 
       def resolved = value
+
+      def dereferenced(_visited = nil) = value
     end
 
     # @visibility private
@@ -124,6 +133,19 @@ module OpenapiFirst
         value
       end
 
+      # Returns a plain Hash with all nested $refs resolved.
+      # A node that is reached again on its own path, as in a recursive schema,
+      # is returned unresolved to stop the recursion.
+      # @param visited [Array<Integer>, nil] Object ids of the nodes on the current path.
+      def dereferenced(visited = nil)
+        return value if visited&.include?(value.object_id)
+
+        visited = mark(visited)
+        return resolve_ref(value['$ref'])&.dereferenced(visited) if value.key?('$ref')
+
+        value.each_key.to_h { |key| [key, self[key]&.dereferenced(visited)] }
+      end
+
       def [](key)
         return resolve_ref(@value['$ref'])[key] if !@value.key?(key) && @value.key?('$ref')
 
@@ -154,6 +176,14 @@ module OpenapiFirst
     class Schema
       extend Forwardable
 
+      # The root context is a document, not a schema. Parsing it with only the core vocabulary
+      # keeps document keys that collide with dialect keywords (like "id" in OpenAPI 3.0)
+      # from being parsed as such and keeps them navigable for $ref pointers.
+      DOCUMENT_META_SCHEMA = JSONSchemer::Schema.new(
+        {},
+        vocabulary: { 'https://json-schema.org/draft/2020-12/vocab/core' => true }
+      )
+
       def initialize(value:, context:, base_uri:, options:)
         @value = value
         @context = context
@@ -167,10 +197,24 @@ module OpenapiFirst
 
       def schema
         @schema ||= begin
-          root_schema = JSONSchemer::Schema.new(context, base_uri:, **options)
+          root_schema = JSONSchemer::Schema.new(context, base_uri:, **options, meta_schema: DOCUMENT_META_SCHEMA)
+          apply_dialect(root_schema)
           JSONSchemer::Schema.new(value, nil, root_schema, base_uri:, **options)
         end
       end
+
+      private
+
+      # Set the dialect meta schema on the root like JSONSchemer::Schema#parse would,
+      # so that schemas resolved via $ref pointers into the document inherit it.
+      def apply_dialect(root_schema)
+        dialect = options[:meta_schema] || options.fetch(:configuration, JSONSchemer.configuration).meta_schema
+        if dialect.is_a?(String)
+          JSONSchemer::Schema::SCHEMA_KEYWORD_CLASS.new(dialect, root_schema, '$schema')
+        else
+          root_schema.meta_schema = dialect
+        end
+      end
     end
 
     # @visibility private
@@ -201,6 +245,15 @@ module OpenapiFirst
           end
         end
       end
+
+      # Returns a plain Array with all nested $refs resolved.
+      # @param visited [Array<Integer>, nil] Object ids of the nodes on the current path.
+      def dereferenced(visited = nil)
+        return value if visited&.include?(value.object_id)
+
+        visited = mark(visited)
+        value.each_index.map { self[_1]&.dereferenced(visited) }
+      end
     end
   end
 end