openapi3_parser 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 39b97559bdb240544c9f0f65b848c71edc28af1c
-  data.tar.gz: b8b1339e8d116a202a16ada58ffb75cf403f608f
+  metadata.gz: 0e48a69a367595cb50a68fbfef79e0d9fc925c61
+  data.tar.gz: a53afad6f342b79d622201e9b87cd014be1eeac8
 SHA512:
-  metadata.gz: 5a9772d8bfd2c67b3736f32aa25d937c08c1fc76f8142bc92685f3cc2f0202a7c74f313d6e836d1ddcf92b15b99084b94e056d53ed299b437eefd15f56387eff
-  data.tar.gz: c47362a370307d40b1497e8b1c67e58ce267efaa611e0f0b49765ab3f2769635aba04f67f611250a1125116cadca09ac4d6d6372290253069192336c641169ba
+  metadata.gz: 2d772db41130444cbb1bfae66508ec1bde2ae21ba583da15b9cf3776d68dee5864f061e5e333a7cd2676361f9ac3bd6362efc4afaccaa0967b47c1fcbc00c781
+  data.tar.gz: 79df18c70a0e16b3d509c669a37be4b421b8b2504e36ff97b4144cbb982123c6d146c77a190eda794abb7ecd8282d41397006ba3284452ba65220e2952f6b6a4

data/.rubocop.yml

@@ -2,6 +2,8 @@ Style/StringLiterals:
   EnforcedStyle: double_quotes
 Metrics/MethodLength:
   Max: 30
+Metrics/AbcSize:
+  Max: 30
 Documentation:
   Enabled: false
 Metrics/BlockLength:

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# Unreleased
+
+- Support for recursive references - fixes: https://github.com/kevindew/openapi3_parser/issues/4
+- `node_at` method on nodes and document to allow looking up nodes by string
+  paths
+- Refactor of the node factory classes to use simpler inheritance rather than
+  the mixins in mixins approach.
+
 # 0.4.0
 
 - Determine the OpenAPI specification version and store it in document.

data/README.md

@@ -31,7 +31,7 @@ You can install this gem into your bundler application by adding this line to
 your Gemfile:
 
 ```
-gem "openapi3_parser", "~> 0.3.0"
+gem "openapi3_parser", "~> 0.5.0"
 ```
 
 and then running `$ bundle install`

data/TODO.md

@@ -3,7 +3,7 @@
 These are the steps defined to reach 1.0. Assistance is very welcome.
 
 - [x] Handle mutually exclusive fields
-- [ ] Refactor the various NodeFactory modules to be a less confusing
+- [x] Refactor the various NodeFactory modules to be a less confusing
       hierachical structure. Consider having factories subclass instead of use
       mixin
 - [x] Decouple Document class for the source file. Consider a source file class
@@ -18,16 +18,16 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [ ] Reach parity with OpenAPI specification for validation
 - [ ] Consider a lenient mode for a document to only have to comply with type
       based validation
-- [ ] Improve test coverage
+- [x] Improve test coverage
 - [ ] Publish documentation of the interface through the structure
 - [x] Consider a resolved context class for representing context with a node
       that can handle scenarios where a node is represented by both a reference
       and resolved context
-- [ ] Create error classes for various scenarios
+- [x] Create error classes for various scenarios
 - [ ] Associate/resolve operation id / operation references
 - [ ] Do something to model expressions
 - [x] Improve the modelling of namespace
-- [ ] Set up nicer string representations of key classes to help them be
+- [x] Set up nicer string representations of key classes to help them be
       debugged
 - [x] Ensure Array and Map nodes return empty ones by default rather than nil
 - [ ] Make JSON pointer public access to be consistent accepting string, array

data/lib/openapi3_parser/array_sentence.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Openapi3Parser
+  module ArraySentence
+    refine ::Array do
+      def sentence_join
+        return join if count < 2
+        self[0..-2].join(", ") + " and " + self[-1]
+      end
+    end
+  end
+end

data/lib/openapi3_parser/cautious_dig.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Openapi3Parser
+  class CautiousDig
+    private_class_method :new
+
+    def self.call(*args)
+      new.call(*args)
+    end
+
+    def call(collection, *segments)
+      segments.inject(collection) do |next_depth, segment|
+        break unless next_depth
+
+        if next_depth.respond_to?(:keys)
+          hash_like(next_depth, segment)
+        elsif next_depth.respond_to?(:[])
+          array_like(next_depth, segment)
+        end
+      end
+    end
+
+    private
+
+    def hash_like(item, segment)
+      key = item.keys.find { |k| segment == k || segment.to_s == k.to_s }
+      item[key]
+    end
+
+    def array_like(item, segment)
+      index = if segment.is_a?(String) && segment =~ /\A\d+\z/
+                segment.to_i
+              else
+                segment
+              end
+      index.is_a?(Integer) ? item[index] : nil
+    end
+  end
+end

data/lib/openapi3_parser/context.rb

@@ -38,6 +38,18 @@ module Openapi3Parser
           referenced_by: pc.referenced_by)
     end
 
+    # Convert a context into one that knows that is a reference
+    #
+    # @param  [Context] current_context
+    # @return [Context]
+    def self.as_reference(current_context)
+      new(current_context.input,
+          document_location: current_context.document_location,
+          source_location: current_context.source_location,
+          referenced_by: current_context.referenced_by,
+          is_reference: true)
+    end
+
     # Creates the context for a field that is referenced by a context.
     # In this scenario the context of the document is the same but we are in
     # a different part of the source file, or even a different source file
@@ -63,14 +75,25 @@ module Openapi3Parser
     # @param  [Context::Location]       document_location
     # @param  [Context::Location, nil]  source_location
     # @param  [Context, nil]            referenced_by
+    # @param  [Boolean]                 is_reference
     def initialize(input,
                    document_location:,
                    source_location: nil,
-                   referenced_by: nil)
+                   referenced_by: nil,
+                   is_reference: false)
       @input = input
       @document_location = document_location
       @source_location = source_location || document_location
       @referenced_by = referenced_by
+      @is_reference = is_reference
+    end
+
+    # @return [Boolean]
+    def ==(other)
+      input == other.input &&
+        document_location == other.document_location &&
+        source_location == other.source_location &&
+        referenced_by == other.referenced_by
     end
 
     # @return [Document]
@@ -93,6 +116,11 @@ module Openapi3Parser
       document_location.pointer.segments
     end
 
+    # @return [Boolean]
+    def reference?
+      @is_reference
+    end
+
     def inspect
       %{#{self.class.name}(document_location: #{document_location}, } +
         %{source_location: #{source_location}), referenced_by: } +
@@ -108,5 +136,29 @@ module Openapi3Parser
     def to_s
       location_summary
     end
+
+    def resolved_input
+      # The resolved input for a reference is at the segment before the
+      # reference
+      pointer = if reference?
+                  document_location.pointer.segments[0...-1]
+                else
+                  document_location.pointer
+                end
+
+      document.resolved_input_at(pointer)
+    end
+
+    def node
+      # The created node for a reference is at the segment before the
+      # reference
+      pointer = if reference?
+                  document_location.pointer.segments[0...-1]
+                else
+                  document_location.pointer
+                end
+
+      document.node_at(pointer)
+    end
   end
 end

data/lib/openapi3_parser/context/location.rb

@@ -22,6 +22,7 @@ module Openapi3Parser
       end
 
       def ==(other)
+        return false unless other.instance_of?(self.class)
         source == other.source && pointer == other.pointer
       end
 

data/lib/openapi3_parser/context/pointer.rb

@@ -7,11 +7,28 @@ module Openapi3Parser
     # A class to decorate the array of fields that make up a pointer and
     # provide common means to convert it into different representations.
     class Pointer
-      attr_reader :segments
+      def self.from_fragment(fragment)
+        fragment = fragment[1..-1] if fragment.start_with?("#")
+        absolute = fragment[0] == "/"
+        segments = fragment.split("/").map do |part|
+          next if part == ""
+          unescaped = CGI.unescape(part.gsub("%20", "+"))
+          unescaped =~ /\A\d+\z/ ? unescaped.to_i : unescaped
+        end
+        new(segments.compact, absolute)
+      end
+
+      def self.merge_pointers(base_pointer, new_pointer)
+        MergePointers.call(base_pointer, new_pointer)
+      end
+
+      attr_reader :segments, :absolute
 
       # @param [::Array] segments
-      def initialize(segments)
+      # @param [Boolean] absolute
+      def initialize(segments, absolute = true)
         @segments = segments.freeze
+        @absolute = absolute
       end
 
       def ==(other)
@@ -19,9 +36,9 @@ module Openapi3Parser
       end
 
       def fragment
-        segments.map { |s| CGI.escape(s.to_s).gsub("+", "%20") }
-                .join("/")
-                .prepend("#/")
+        fragment = segments.map { |s| CGI.escape(s.to_s).gsub("+", "%20") }
+                           .join("/")
+        "#" + (absolute ? fragment.prepend("/") : fragment)
       end
 
       def to_s
@@ -31,6 +48,51 @@ module Openapi3Parser
       def inspect
         %{#{self.class.name}(segments: #{segments}, fragment: "#{fragment}")}
       end
+
+      class MergePointers
+        private_class_method :new
+
+        def self.call(*args)
+          new(*args).call
+        end
+
+        def initialize(base_pointer, new_pointer)
+          @base_pointer = create_pointer(base_pointer)
+          @new_pointer = create_pointer(new_pointer)
+        end
+
+        def call
+          return base_pointer if new_pointer.nil?
+          return new_pointer if base_pointer.nil? || new_pointer.absolute
+
+          merge_pointers(base_pointer, new_pointer)
+        end
+
+        private
+
+        attr_reader :base_pointer, :new_pointer
+
+        def create_pointer(pointer_like)
+          case pointer_like
+          when Pointer then pointer_like
+          when ::Array then Pointer.new(pointer_like, false)
+          when ::String then Pointer.from_fragment(pointer_like)
+          when nil then nil
+          else raise Openapi3Parser::Error, "Unexpected type for pointer"
+          end
+        end
+
+        def merge_pointers(pointer_a, pointer_b)
+          fragment_a = pointer_a.fragment.gsub(%r{\A#?/?}, "")
+          fragment_b = pointer_b.fragment.gsub(%r{\A#?/?}, "")
+
+          joined = File.expand_path("/#{fragment_a}/#{fragment_b}", "/")
+
+          joined = joined[1..-1] unless pointer_a.absolute
+
+          Pointer.from_fragment("##{joined}")
+        end
+      end
     end
   end
 end

data/lib/openapi3_parser/document.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "openapi3_parser/cautious_dig"
 require "openapi3_parser/context"
+require "openapi3_parser/context/pointer"
 require "openapi3_parser/document/reference_register"
 require "openapi3_parser/error"
-require "openapi3_parser/node_factories/openapi"
+require "openapi3_parser/node_factory/openapi"
 require "openapi3_parser/source"
 require "openapi3_parser/validation/error_collection"
 
@@ -79,9 +81,11 @@ module Openapi3Parser
     #   @return Object
     # @!method each
     #   Iterate through the attributes of the root object
-    #   @see Node::Object#each
+    # @!method keys
+    #   Access keys of the root object
     def_delegators :root, :openapi, :info, :servers, :paths, :components,
-                   :security, :tags, :external_docs, :extension, :[], :each
+                   :security, :tags, :external_docs, :extension, :[], :each,
+                   :keys
 
     # @param [SourceInput] source_input
     def initialize(source_input)
@@ -132,10 +136,47 @@ module Openapi3Parser
       sources.find { |source| source.source_input == source_input }
     end
 
+    # Look up the resolved input for an address in the OpenAPI document,
+    # resolved_input refers to the input with references resolevd and all
+    # optional fields existing
+    #
+    # @param [Context::Pointer, String, Array]      pointer
+    # @param [Context::Pointer, String, Array, nil] relative_to
+    # @return anything
+    def resolved_input_at(pointer, relative_to = nil)
+      look_up_pointer(pointer, relative_to, factory.resolved_input)
+    end
+
+    # Look up a node at a particular location in the OpenAPI docuemnt
+    #
+    # Examples:
+    #
+    # document.node_at("#/components/schemas")
+    # document.node_at(%w[components schemas])
+    #
+    # @param [Context::Pointer, String, Array]      pointer
+    # @param [Context::Pointer, String, Array, nil] relative_to
+    # @return anything
+    def node_at(pointer, relative_to = nil)
+      look_up_pointer(pointer, relative_to, root)
+    end
+
+    # @return [String]
+    def inspect
+      %{#{self.class.name}(openapi_version: #{openapi_version}, } +
+        %{root_source: #{root_source.inspect})}
+    end
+
     private
 
     attr_reader :reference_register, :built, :build_in_progress
 
+    def look_up_pointer(pointer, relative_pointer, subject)
+      merged_pointer = Context::Pointer.merge_pointers(relative_pointer,
+                                                       pointer)
+      CautiousDig.call(subject, *merged_pointer.segments)
+    end
+
     def add_warning(text)
       @warnings << text
     end
@@ -144,7 +185,7 @@ module Openapi3Parser
       return if build_in_progress || built
       @build_in_progress = true
       context = Context.root(root_source.data, root_source)
-      @factory = NodeFactories::Openapi.new(context)
+      @factory = NodeFactory::Openapi.new(context)
       reference_register.freeze
       @warnings.freeze
       @build_in_progress = false

data/lib/openapi3_parser/error.rb

@@ -27,5 +27,14 @@ module Openapi3Parser
     # Used when there are extra fields that are not expected in the data for
     # a node
     class UnexpectedFields < Error; end
+    # Used when a method we expect to be able to call (through symbol or proc)
+    # is not callable
+    class NotCallable < Error; end
+    # Raised when we in a recursive data structure and can't perform an
+    # operation
+    class InRecursiveStructure < Error; end
+    # Used when we're trying to validate that a type is something that is not
+    # validatable, most likely a sign that we're in a bug
+    class UnvalidatableType < Error; end
   end
 end

data/lib/openapi3_parser/node/array.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 require "openapi3_parser/node/map"
 
 module Openapi3Parser
@@ -11,8 +13,10 @@ module Openapi3Parser
     # The contents of the data will be dependent on where this document is in
     # the document hierachy.
     class Array
+      extend Forwardable
       include Enumerable
 
+      def_delegators :node_data, :each, :[], :empty?
       attr_reader :node_data, :node_context
 
       # @param [::Array] data     data used to populate this node
@@ -22,12 +26,18 @@ module Openapi3Parser
         @node_context = context
       end
 
-      def [](value)
-        node_data[value]
+      # Used to access a node relative to this node
+      # @param  [Context::Pointer, ::Array, ::String] pointer_like
+      # @return anything
+      def node_at(pointer_like)
+        current_pointer = node_context.document_location.pointer
+        node_context.document.node_at(pointer_like, current_pointer)
       end
 
-      def each(&block)
-        node_data.each(&block)
+      # @return [String]
+      def inspect
+        fragment = node_context.document_location.pointer.fragment
+        %{#{self.class.name}(#{fragment})}
       end
     end
   end