openapi3_parser 0.2.0 → 0.3.0

data/lib/openapi3_parser/nodes/path_item.rb

@@ -58,13 +58,12 @@ module Openapi3Parser
         node_data["trace"]
       end
 
-      # @return [Nodes::Array] a collection of {Server}[./Server.html] objects
+      # @return [Nodes::Array<Server>]
       def servers
         node_data["servers"]
       end
 
-      # @return [Nodes::Array] a collection of {Parameter}[./Parameter.html]
-      #         objects
+      # @return [Nodes::Array<Parameter>]
       def parameters
         node_data["parameters"]
       end

data/lib/openapi3_parser/nodes/request_body.rb

@@ -13,7 +13,7 @@ module Openapi3Parser
         node_data["description"]
       end
 
-      # @return [Map] a map of String: {MediaType}[./MediaType.html] objects
+      # @return [Map<String, MediaType>]
       def content
         node_data["content"]
       end

data/lib/openapi3_parser/nodes/response.rb

@@ -13,17 +13,17 @@ module Openapi3Parser
         node_data["description"]
       end
 
-      # @return [Map] a map of String: {Header}[./Header.html] objects
+      # @return [Map<String, Header>]
       def headers
         node_data["headers"]
       end
 
-      # @return [Map] a map of String: {MediaType}[./MediaType.html] objects
+      # @return [Map<String, MediaType>]
       def content
         node_data["content"]
       end
 
-      # @return [Map] a map of String: {Link}[./Link.html] objects
+      # @return [Map<String, Link>]
       def links
         node_data["links"]
       end

data/lib/openapi3_parser/nodes/schema.rb

@@ -79,13 +79,12 @@ module Openapi3Parser
         node_data["minProperties"]
       end
 
-      # @return [Nodes::Array, nil] a collection of String objects or nil
+      # @return [Nodes::Array<String>, nil]
       def required
         node_data["required"]
       end
 
-      # @return [Nodes::Array, nil] a collection of objects of no fixed type or
-      #         nil
+      # @return [Nodes::Array<Object>, nil]
       def enum
         node_data["enum"]
       end
@@ -95,17 +94,17 @@ module Openapi3Parser
         node_data["type"]
       end
 
-      # @return [Nodes::Array, nil] a collection of Schema objects or nil
+      # @return [Nodes::Array<Schema>, nil]
       def all_of
         node_data["allOf"]
       end
 
-      # @return [Nodes::Array, nil] a collection of Schema objects or nil
+      # @return [Nodes::Array<Schema>, nil]
       def one_of
         node_data["oneOf"]
       end
 
-      # @return [Nodes::Array, nil] a collection of Schema objects or nil
+      # @return [Nodes::Array<Schema>, nil]
       def any_of
         node_data["anyOf"]
       end
@@ -120,7 +119,7 @@ module Openapi3Parser
         node_data["items"]
       end
 
-      # @return [Map] a collection of Schema objects
+      # @return [Map<String, Schema>]
       def properties
         node_data["properties"]
       end

data/lib/openapi3_parser/nodes/server.rb

@@ -18,8 +18,7 @@ module Openapi3Parser
         node_data["description"]
       end
 
-      # @return [Map] a map of String: {ServerVariable}[./ServerVariable.html]
-      #         objects
+      # @return [Map<String, ServerVariable>]
       def variables
         node_data["variables"]
       end

data/lib/openapi3_parser/nodes/server_variable.rb

@@ -8,7 +8,7 @@ module Openapi3Parser
     class ServerVariable
       include Node::Object
 
-      # @return [Nodes::Array, nil] a collection of String objects or nil
+      # @return [Nodes::Array<String>, nil]
       def enum
         node_data["enum"]
       end

data/lib/openapi3_parser/source.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/error"
+require "openapi3_parser/source/reference"
+require "openapi3_parser/source/reference_resolver"
+
+module Openapi3Parser
+  # Represents a source of data used to produce the OpenAPI document. Documents
+  # which do not have any references to external files will only have a single
+  # source
+  #
+  # @attr_reader [SourceInput]                  source_input
+  #   The source input which provides the data
+  # @attr_reader [Document]                     document
+  #   The document that this source is associated with
+  # @attr_reader [Document::ReferenceRegister]  reference_register
+  #   An object to track references for a document
+  # @attr_reader [Source, nil]                  parent
+  #   Set to a Source if this source was created due to a reference within
+  #   a different Source
+  class Source
+    attr_reader :source_input, :document, :reference_register, :parent
+
+    # @param  [SourceInput]                   source_input
+    # @param  [Document]                      document
+    # @param  [Document::ReferenceRegister]   reference_register
+    # @param  [Source, nil]                   parent
+    def initialize(source_input, document, reference_register, parent = nil)
+      @source_input = source_input
+      @document = document
+      @reference_register = reference_register
+      @parent = parent
+    end
+
+    # The data from the source
+    def data
+      @data ||= normalize_data(source_input.contents)
+    end
+
+    # @see SourceInput#available?
+    def available?
+      source_input.available?
+    end
+
+    # Whether this is the root source of a document
+    def root?
+      document.root_source == self
+    end
+
+    # Used to register a reference with the underlying document and return a
+    # reference resolver to access the object referenced
+    #
+    # @param  [String]        given_reference   The reference as text
+    # @param  [NodeFactory]   factory           Factory class for the expected
+    #                                           eventual resource
+    # @param  [Context]       context           The context of the object
+    #                                           calling this reference
+    # @return [ReferenceResolver]
+    def register_reference(given_reference, factory, context)
+      reference = Reference.new(given_reference)
+      ReferenceResolver.new(
+        reference, factory, context
+      ).tap do |resolver|
+        next if resolver.in_root_source?
+        reference_register.register(resolver.reference_factory)
+      end
+    end
+
+    # Access/create the source object for a reference
+    #
+    # @param  [Reference] reference
+    # @return [Source]
+    def resolve_source(reference)
+      if reference.only_fragment?
+        # I found the spec wasn't fully clear on expected behaviour if a source
+        # references a fragment that doesn't exist in it's current document
+        # and just the root source. I'm assuming to be consistent with URI a
+        # fragment only reference only references current JSON document. This
+        # could be incorrect though.
+        self
+      else
+        next_source_input = source_input.resolve_next(reference)
+        source = document.source_for_source_input(next_source_input)
+        source || self.class.new(next_source_input,
+                                 document,
+                                 reference_register,
+                                 self)
+      end
+    end
+
+    # Access the data in a source at a particular pointer
+    #
+    # @param  [Array] json_pointer  An array of segments of a JSON pointer
+    # @return [Object]
+    def data_at_pointer(json_pointer)
+      return data if json_pointer.empty?
+      data.dig(*json_pointer) if data.respond_to?(:dig)
+    end
+
+    # Whether the source has data at the particular pointer
+    def has_pointer?(json_pointer) # rubocop:disable Naming/PredicateName
+      !data_at_pointer(json_pointer).nil?
+    end
+
+    # @return [String]
+    def relative_to_root
+      return "" if root?
+      source_input.relative_to(document.root_source.source_input)
+    end
+
+    def ==(other)
+      source_input == other.source_input && document == other.document
+    end
+
+    # return [String]
+    def inspect
+      %{#{self.class.name}(input: #{source_input})}
+    end
+
+    private
+
+    def normalize_data(input)
+      normalized = if input.respond_to?(:keys)
+                     input.each_with_object({}) do |(key, value), memo|
+                       memo[key.to_s.freeze] = normalize_data(value)
+                     end
+                   elsif input.respond_to?(:map)
+                     input.map { |v| normalize_data(v) }
+                   else
+                     input
+                   end
+
+      normalized.freeze
+    end
+  end
+end

data/lib/openapi3_parser/source/reference.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/source"
+require "openapi3_parser/validators/reference"
+
+module Openapi3Parser
+  class Source
+    # An object which represents a reference that can be indicated in a OpenAPI
+    # file. Given a string reference it can be used to answer key questions
+    # that aid in resolving the reference
+    #
+    # e.g.
+    # r = Openapi3Parser::Source::Reference.new("test.yaml#/path/to/item")
+    #
+    # r.only_fragment?
+    # => false
+    #
+    # r.rsource_uri
+    # => "test.yaml"
+    class Reference
+      # @param [String] reference   reference from an OpenAPI file
+      def initialize(reference)
+        @given_reference = reference
+      end
+
+      def to_s
+        given_reference.to_s
+      end
+
+      def only_fragment?
+        resource_uri.to_s == ""
+      end
+
+      # @return [String, nil]
+      def fragment
+        uri.fragment
+      end
+
+      # @return [URI]
+      def resource_uri
+        uri_without_fragment
+      end
+
+      def absolute?
+        uri.absolute?
+      end
+
+      # @return [::Array] an array of strings of the components in the fragment
+      def json_pointer
+        @json_pointer ||= (fragment || "").split("/").drop(1).map do |field|
+          CGI.unescape(field.gsub("+", "%20"))
+        end
+      end
+
+      private
+
+      attr_reader :given_reference
+
+      def uri
+        @uri = URI.parse(given_reference)
+      end
+
+      def uri_without_fragment
+        @uri_without_fragment ||= uri.dup.tap { |u| u.fragment = nil }
+      end
+    end
+  end
+end

data/lib/openapi3_parser/source/reference_resolver.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/context"
+require "openapi3_parser/source"
+
+module Openapi3Parser
+  class Source
+    class ReferenceResolver
+      def initialize(reference, factory, context)
+        @reference = reference
+        @factory = factory
+        @context = context
+      end
+
+      def reference_factory
+        @reference_factory ||= begin
+                                 next_context = Context.reference_field(
+                                   context,
+                                   input: source.data_at_pointer(json_pointer),
+                                   source: source,
+                                   pointer_segments: json_pointer
+                                 )
+                                 build_factory(next_context)
+                               end
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        @errors ||= Array(build_errors)
+      end
+
+      def node
+        reference_factory.node
+      end
+
+      def in_root_source?
+        source == context.document.root_source
+      end
+
+      private
+
+      attr_reader :reference, :factory, :context
+
+      def source
+        @source ||= context.source.resolve_source(reference)
+      end
+
+      def build_errors
+        return source_unavailabe_error unless source.available?
+        return pointer_missing_error unless source.has_pointer?(json_pointer)
+        resolution_error unless reference_factory.valid?
+      end
+
+      def source_unavailabe_error
+        # @todo include a location
+        "Source is unavailable"
+      end
+
+      def pointer_missing_error
+        # @todo include a location and a pointer
+        "Source does not have pointer"
+      end
+
+      def resolution_error
+        # @todo include exepected object
+        "Reference does not resolve to a valid object"
+      end
+
+      def json_pointer
+        reference.json_pointer
+      end
+
+      def build_factory(context)
+        factory.is_a?(Class) ? factory.new(context) : factory.call(context)
+      end
+    end
+  end
+end

data/lib/openapi3_parser/source_input.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/error"
+
+module Openapi3Parser
+  # An abstract class which is used to provide a foundation for classes that
+  # represent the different means of input an OpenAPI document can have. It is
+  # used to represent the underlying source of the data which is used as a
+  # source within an OpenAPI document.
+  #
+  # @see SourceInput::Raw   SourceInput::Raw for an input that is done through
+  #                         data, such as a Hash.
+  #
+  # @see SourceInput::File  SourceInput::File for an input that is done through
+  #                         the path to a file within the local file system.
+  #
+  # @see SourceInput::Url   SourceInput::Url for an input that is done through]
+  #                         a URL to an OpenAPI Document
+  #
+  # @attr_reader [Error::InaccessibleInput, nil]  access_error
+  # @attr_reader [Error::UnparsableInput, nil]    parse_error
+  class SourceInput
+    attr_reader :access_error, :parse_error
+
+    # Indicates that the data within this input is suitable (i.e. can parse
+    # underlying JSON or YAML) for trying to use as part of a Document
+    def available?
+      access_error.nil? && parse_error.nil?
+    end
+
+    # For a given reference use the context of the current SourceInput to
+    # determine which file is required for the reference. This allows
+    # references to use relative file paths because we can combine them witt
+    # the current SourceInput location to determine the next one
+    def resolve_next(_reference); end
+
+    # Used to determine whether a different instance of SourceInput is
+    # the same file/data
+    def ==(_other); end
+
+    # The parsed data from the input
+    #
+    # @raise [Error::InaccessibleInput] In cases where the file does not exist
+    # @raise [Error::UnparsableInput]   In cases where the data is not parsable
+    #
+    # @return Object
+    def contents
+      raise access_error if access_error
+      raise parse_error if parse_error
+      @contents
+    end
+
+    # The relative path, if possible, for this source_input compared to a
+    # different one. Defaults to empty string and should be specialised in
+    # subclasses
+    #
+    # @return [String]
+    def relative_to(_source_input)
+      ""
+    end
+
+    private
+
+    def initialize_contents
+      return if access_error
+      @contents = parse_contents
+    rescue ::StandardError => e
+      @parse_error = Error::UnparsableInput.new(e.message)
+    end
+  end
+end