openapi3_parser 0.2.0 → 0.3.0

data/lib/openapi3_parser/document/reference_register.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/error"
+
+module Openapi3Parser
+  class Document
+    class ReferenceRegister
+      attr_reader :sources, :factories
+
+      def initialize
+        @sources = []
+        @factories = []
+      end
+
+      def register(factory)
+        error = "Can't register references when the register is frozen"
+        raise Error::ImmutableObject, error if frozen?
+        context = factory.context
+        add_source(context.source_location.source)
+        add_factory(factory)
+      end
+
+      def freeze
+        sources.freeze
+        factories.freeze
+        super
+      end
+
+      private
+
+      def add_source(source)
+        return if sources.include?(source)
+        sources << source
+      end
+
+      def add_factory(factory)
+        return if factory_registered?(factory)
+        factories << factory
+      end
+
+      def factory_registered?(factory)
+        source_location = factory.context.source_location
+        factories.any? do |f|
+          same_location = f.context.source_location == source_location
+          same_location && f.class == factory.class
+        end
+      end
+    end
+  end
+end

data/lib/openapi3_parser/error.rb

@@ -1,5 +1,31 @@
 # frozen_string_literal: true
 
 module Openapi3Parser
-  class Error < ::RuntimeError; end
+  # An abstract class for Exceptions produced by this Gem
+  class Error < ::RuntimeError
+    # Raised in cases where we have been provided a path or URL to a file and
+    # at runtime when we have tried to access that resource it is not available
+    # for whatever reason.
+    class InaccessibleInput < Error; end
+    # Raised in cases where we provided data that we expected to be parsable
+    # (such as a string of JSON data) but when we tried to parse it an error
+    # is raised
+    class UnparsableInput < Error; end
+    # Raised in cases where an object that is in an immutable state is modified
+    #
+    # Typically this would occur when a component that is frozen is modififed.
+    # Some components are mutable during the construction of a document and
+    # then frozen afterwards.
+    class ImmutableObject < Error; end
+    # Raised when a type that is not a whitelist of valid types is used
+    class InvalidType < Error; end
+    # Raised when we have to abort creating an object due to invalid data
+    class InvalidData < Error; end
+    # Used when there are fields that are missing from an object which prevents
+    # us from creating a node
+    class MissingFields < Error; end
+    # Used when there are extra fields that are not expected in the data for
+    # a node
+    class UnexpectedFields < Error; end
+  end
 end

data/lib/openapi3_parser/node/object.rb

@@ -12,14 +12,39 @@ module Openapi3Parser
         @node_context = context
       end
 
+      # Look up an attribute of the node by the name it has in the OpenAPI
+      # document.
+      #
+      # @example Look up by OpenAPI naming
+      #   obj["externalDocs"]
+      #
+      # @example Look up by symbol
+      #   obj[:servers]
+      #
+      # @example Look up an extension
+      #   obj["x-myExtension"]
+      #
+      # @param [String, Symbol] value
+      #
+      # @return anything
       def [](value)
-        node_data[value]
+        node_data[value.to_s]
       end
 
+      # Look up an extension provided for this object, doesn't need a prefix of
+      # "x-"
+      #
+      # @example Looking up an extension provided as "x-extra"
+      #   obj.extension("extra")
+      #
+      # @param [String, Symbol] value
+      #
+      # @return [Hash, Array, Numeric, String, true, false, nil]
       def extension(value)
         node_data["x-#{value}"]
       end
 
+      # Iterate through the attributes of this object
       def each(&block)
         node_data.each(&block)
       end

data/lib/openapi3_parser/node_factories/array.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "openapi3_parser/context"
+require "openapi3_parser/error"
 require "openapi3_parser/node_factory"
 require "openapi3_parser/nodes/array"
 require "openapi3_parser/validation/error"
+require "openapi3_parser/validation/error_collection"
 
 module Openapi3Parser
   module NodeFactories
@@ -17,11 +20,11 @@ module Openapi3Parser
         value_factory: nil,
         validate: nil
       )
-        super(context)
         @default = default
         @given_value_input_type = value_input_type
         @given_value_factory = value_factory
         @given_validate = validate
+        super(context)
       end
 
       private
@@ -32,7 +35,7 @@ module Openapi3Parser
       def process_input(input)
         input.each_with_index.map do |value, i|
           if value_factory?
-            initialize_value_factory(context.next_namespace(i))
+            initialize_value_factory(Context.next_field(context, i))
           else
             value
           end
@@ -43,15 +46,13 @@ module Openapi3Parser
         given_validate&.call(input, context)
       end
 
-      def validate_input(error_collection)
-        super(error_collection)
-        processed_input.each do |value|
-          next unless value.respond_to?(:errors)
-          error_collection.merge(value.errors)
+      def validate_input
+        value_errors = processed_input.flat_map do |value|
+          value.respond_to?(:errors) ? value.errors.to_a : []
         end
-        error_collection.merge(
-          validate_value_input_type(processed_input, context)
-        )
+        errors = value_errors + validate_value_input_type(processed_input,
+                                                          context)
+        Validation::ErrorCollection.combine(super, errors)
       end
 
       def build_node(input)
@@ -81,7 +82,7 @@ module Openapi3Parser
           error = error_for_value_input_type(value)
           next unless error
           memo << Validation::Error.new(
-            context.next_namespace(i), error
+            error, Context.next_field(context, i), self.class
           )
         end
       end
@@ -90,9 +91,9 @@ module Openapi3Parser
         input.each_with_index do |value, i|
           error = error_for_value_input_type(value)
           next unless error
-          next_context = context.next_namespace(i)
-          raise Openapi3Parser::Error,
-                "Invalid type for #{next_context.stringify_namespace}. "\
+          next_context = Context.next_field(context, i)
+          raise Openapi3Parser::Error::InvalidType,
+                "Invalid type for #{next_context.location_summary}. "\
                 "#{error}"
         end
       end

data/lib/openapi3_parser/node_factories/callback.rb

@@ -14,7 +14,8 @@ module Openapi3Parser
       def process_input(input)
         input.each_with_object({}) do |(key, value), memo|
           memo[key] = value if extension?(key)
-          memo[key] = NodeFactories::PathItem.new(context.next_namespace(key))
+          next_context = Context.next_field(context, key)
+          memo[key] = NodeFactories::PathItem.new(next_context)
         end
       end
 

data/lib/openapi3_parser/node_factories/link.rb

@@ -12,7 +12,7 @@ module Openapi3Parser
 
       allow_extensions
 
-      # @TODO The link object in OAS is pretty meaty and there's lot of scope
+      # @todo The link object in OAS is pretty meaty and there's lot of scope
       # for further work here to make use of it's funcationality
 
       field "operationRef", input_type: String

data/lib/openapi3_parser/node_factories/map.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "openapi3_parser/context"
+require "openapi3_parser/error"
 require "openapi3_parser/node_factory/map"
 require "openapi3_parser/nodes/map"
 require "openapi3_parser/validation/error"
+require "openapi3_parser/validation/error_collection"
 
 module Openapi3Parser
   module NodeFactories
@@ -16,11 +19,11 @@ module Openapi3Parser
         value_factory: nil,
         validate: nil
       )
-        super(context)
         @given_key_input_type = key_input_type
         @given_value_input_type = value_input_type
         @given_value_factory = value_factory
         @given_validate = validate
+        super(context)
       end
 
       private
@@ -31,7 +34,8 @@ module Openapi3Parser
       def process_input(input)
         input.each_with_object({}) do |(key, value), memo|
           memo[key] = if value_factory?
-                        initialize_value_factory(context.next_namespace(key))
+                        next_context = Context.next_field(context, key)
+                        initialize_value_factory(next_context)
                       else
                         value
                       end
@@ -53,11 +57,9 @@ module Openapi3Parser
         given_validate&.call(input, context)
       end
 
-      def validate_input(error_collection)
-        super(error_collection)
-        error_collection.merge(
-          validate_value_input_type(processed_input, context)
-        )
+      def validate_input
+        errors = validate_value_input_type(processed_input, context)
+        Validation::ErrorCollection.combine(super, errors)
       end
 
       def build_node(input)
@@ -84,7 +86,7 @@ module Openapi3Parser
           error = error_for_value_input_type(value)
           next unless error
           memo << Validation::Error.new(
-            context.next_namespace(key), error
+            error, Context.next_field(context, key), self.class
           )
         end
       end
@@ -93,9 +95,9 @@ module Openapi3Parser
         input.each do |key, value|
           error = error_for_value_input_type(value)
           next unless error
-          next_context = context.next_namespace(key)
-          raise Openapi3Parser::Error,
-                "Invalid type for #{next_context.stringify_namespace}. "\
+          next_context = Context.next_field(context, key)
+          raise Openapi3Parser::Error::InvalidType,
+                "Invalid type for #{next_context.location_summary}. "\
                 "#{error}"
         end
       end

data/lib/openapi3_parser/node_factories/openapi.rb

@@ -17,6 +17,8 @@ module Openapi3Parser
       include NodeFactory::Object
 
       allow_extensions
+      disallow_default
+
       field "openapi", input_type: String, required: true
       field "info", factory: NodeFactories::Info, required: true
       field "servers", factory: :servers_factory

data/lib/openapi3_parser/node_factories/path_item.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "openapi3_parser/nodes/path_item"
+require "openapi3_parser/node_factory/fields/reference"
 require "openapi3_parser/node_factory/object"
 require "openapi3_parser/node_factory/object/node_builder"
 require "openapi3_parser/node_factory/optional_reference"
@@ -15,7 +16,7 @@ module Openapi3Parser
       include NodeFactory::Object
 
       allow_extensions
-      field "$ref", input_type: String
+      field "$ref", input_type: String, factory: :ref_factory
       field "summary", input_type: String
       field "description", input_type: String
       field "get", factory: :operation_factory
@@ -36,9 +37,17 @@ module Openapi3Parser
       private
 
       def build_object(data, context)
-        merged_data = merge_reference(data, context)
-        merged_data.delete("$ref")
-        Nodes::PathItem.new(merged_data, context)
+        ref = data.delete("$ref")
+        return Nodes::PathItem.new(data, context) unless ref
+
+        merged_data = ref.node_data.merge(data) do |_, new, old|
+          new.nil? ? old : new
+        end
+        Nodes::PathItem.new(merged_data, ref.node_context)
+      end
+
+      def ref_factory(context)
+        Fields::Reference.new(context, self.class)
       end
 
       def operation_factory(context)
@@ -56,20 +65,6 @@ module Openapi3Parser
         factory = NodeFactory::OptionalReference.new(NodeFactories::Parameter)
         NodeFactories::Array.new(context, value_factory: factory)
       end
-
-      def merge_reference(data, context)
-        return data unless data["$ref"]
-        factory = context.resolve_reference do |ref_context|
-          self.class.new(ref_context)
-        end
-
-        # @TODO In this situation we're basically sacrificing the reference
-        # context as we don't know how to merge them. Should develop a system
-        # to have a dual context
-        factory.node_data.merge(data) do |_, new, old|
-          new.nil? ? old : new
-        end
-      end
     end
   end
 end

data/lib/openapi3_parser/node_factories/paths.rb

@@ -15,7 +15,8 @@ module Openapi3Parser
       def process_input(input)
         input.each_with_object({}) do |(key, value), memo|
           memo[key] = value if extension?(key)
-          memo[key] = child_factory(context.next_namespace(key))
+          next_context = Context.next_field(context, key)
+          memo[key] = child_factory(next_context)
         end
       end
 

data/lib/openapi3_parser/node_factories/reference.rb

@@ -1,32 +1,30 @@
 # frozen_string_literal: true
 
 require "openapi3_parser/node_factory/object"
+require "openapi3_parser/node_factory/fields/reference"
 
 module Openapi3Parser
   module NodeFactories
     class Reference
       include NodeFactory::Object
 
-      field "$ref", input_type: String, required: true
+      field "$ref", input_type: String, required: true, factory: :ref_factory
 
       attr_reader :factory
 
       def initialize(context, factory)
-        super(context)
         @factory = factory
+        super(context)
       end
 
       private
 
-      def build_object(_, context)
-        context.resolve_reference do |ref_context|
-          resolve_factory(ref_context).node
-        end
+      def build_node(input)
+        input["$ref"].node
       end
 
-      def resolve_factory(ref_context)
-        return factory.new(ref_context) if factory.is_a?(Class)
-        factory.call(ref_context)
+      def ref_factory(context)
+        Fields::Reference.new(context, factory)
       end
     end
   end

data/lib/openapi3_parser/node_factories/responses.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
+require "openapi3_parser/context"
+require "openapi3_parser/node_factories/response"
 require "openapi3_parser/node_factory/map"
 require "openapi3_parser/node_factory/optional_reference"
 require "openapi3_parser/nodes/responses"
-require "openapi3_parser/node_factories/response"
 
 module Openapi3Parser
   module NodeFactories
@@ -15,7 +16,8 @@ module Openapi3Parser
       def process_input(input)
         input.each_with_object({}) do |(key, value), memo|
           memo[key] = value if extension?(key)
-          memo[key] = child_factory(context.next_namespace(key))
+          next_context = Context.next_field(context, key)
+          memo[key] = child_factory(next_context)
         end
       end
 

data/lib/openapi3_parser/node_factories/security_requirement.rb

@@ -13,7 +13,8 @@ module Openapi3Parser
 
       def process_input(input)
         input.keys.each_with_object({}) do |key, memo|
-          memo[key] = NodeFactories::Array.new(context.next_namespace(key))
+          next_context = Context.next_field(context, key)
+          memo[key] = NodeFactories::Array.new(next_context)
         end
       end
 

data/lib/openapi3_parser/node_factory.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "openapi3_parser/context"
 require "openapi3_parser/error"
 require "openapi3_parser/validation/error"
 require "openapi3_parser/validation/error_collection"
@@ -19,18 +20,36 @@ module Openapi3Parser
       def expected_input_type
         @input_type
       end
+
+      def allow_default
+        @allow_default = true
+      end
+
+      def disallow_default
+        @allow_default = false
+      end
+
+      def allowed_default?
+        @allow_default.nil? || @allow_default
+      end
     end
 
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    def allowed_default?
+      self.class.allowed_default?
+    end
+
     EXTENSION_REGEX = /^x-(.*)/
 
     attr_reader :context
 
     def initialize(context)
       @context = context
+      input = nil_input? ? default : context.input
+      @processed_input = input.nil? ? nil : process_input(input)
     end
 
     def valid?
@@ -51,47 +70,44 @@ module Openapi3Parser
 
     private
 
+    attr_reader :processed_input
+
     def validate(_input, _context); end
 
-    def validate_input(error_collection)
-      add_validation_errors(
-        validate(context.input, context),
-        error_collection
-      )
+    def validate_input
+      transform_errors(validate(context.input, context))
     end
 
-    def add_validation_errors(errors, error_collection)
-      errors = Array(errors)
-      errors.each do |error|
-        unless error.is_a?(Validation::Error)
-          error = Validation::Error.new(context.namespace, error)
+    def transform_errors(errors)
+      error_objects = Array(errors).map do |error|
+        if !error.is_a?(Validation::Error)
+          error
+        else
+          Validation::Error.new(error, context, self.class)
         end
-        error_collection.append(error)
       end
-      error_collection
+      Validation::ErrorCollection.new(error_objects)
     end
 
     def build_errors
-      error_collection = Validation::ErrorCollection.new
-      return error_collection if nil_input?
+      return Validation::ErrorCollection.new if nil_input? && allowed_default?
       unless valid_type?
         error = Validation::Error.new(
-          context.namespace, "Invalid type. #{validate_type}"
+          "Invalid type. #{validate_type}", context, self.class
         )
-        return error_collection.tap { |ec| ec.append(error) }
+        return Validation::ErrorCollection.new([error])
       end
-      validate_input(error_collection)
-      error_collection
+      validate_input
     end
 
     def build_valid_node
-      if nil_input?
+      if nil_input? && allowed_default?
         return default.nil? ? nil : build_node(processed_input)
       end
 
       unless valid_type?
-        raise Openapi3Parser::Error,
-              "Invalid type for #{context.stringify_namespace}. "\
+        raise Openapi3Parser::Error::InvalidType,
+              "Invalid type for #{context.location_summary}. "\
               "#{validate_type}"
       end
 
@@ -102,8 +118,8 @@ module Openapi3Parser
     def validate_before_build
       errors = Array(validate(context.input, context))
       return unless errors.any?
-      raise Openapi3Parser::Error,
-            "Invalid data for #{context.stringify_namespace}. "\
+      raise Openapi3Parser::Error::InvalidData,
+            "Invalid data for #{context.location_summary}. "\
             "#{errors.join(', ')}"
     end
 
@@ -116,13 +132,6 @@ module Openapi3Parser
       return "Expected #{self.class.expected_input_type}" unless valid_type
     end
 
-    def processed_input
-      @processed_input ||= begin
-                             input = nil_input? ? default : context.input
-                             process_input(input)
-                           end
-    end
-
     def process_input(input)
       input
     end