openapi3_parser 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f60ae34f39675f7ce3616bd96dc3e383275d117d
-  data.tar.gz: 4ecf6bffd69c875778c4d096f29cf7b5deadbf7e
+  metadata.gz: 651f457272264ca4fc7b45040203a9fa7deeabde
+  data.tar.gz: b00561ee20a2c121d9f1d030511b07870cd66ecc
 SHA512:
-  metadata.gz: f5a96679f760117e345c9e992161444c06df7d667953fad6badf547dd83dee449b672cc9f265a26a7166e2cdec887d5205bf0dcda6abdbece2a2ce74aeb61153
-  data.tar.gz: 087aea7ab5f4abceb69b9acce6854f70dac44fca1620bde695d7dd1a7813ca1a468728e3cc5a08ab5ae31d5320c75459f9537ce584c6ffbff082ca796d9a3602
+  metadata.gz: a38facc684d56b0194066ba88db7396107d882bc225fa07f14600bf21a5156c2f6032f8b284bac5146a6f3a9e792147e63fd35ca915b8b8d2f36fe57e738a662
+  data.tar.gz: f605fd5997afe6055b6e627eaca9971dd60dd6f2fbc19381a363490a596f46cf001317aed21130c4273115143c6353516c035747ab16867b62ece619434b6b1a

data/.travis.yml

@@ -1,4 +1,13 @@
 language: ruby
 sudo: false
 rvm:
-- 2.3.1
+  - 2.3.6
+  - 2.4.3
+  - jruby-9.1.15.0
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+  fast_finish: true

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.3.0
+
+- Allow opening files by URL
+- Support references in different files
+
 # 0.2.0
 
 - Allow defaulting to empty arrays and maps

data/README.md

@@ -25,6 +25,19 @@ Documentation for the API to navigate the OpenAPI nodes is available on
 [openapi-3]: https://github.com/OAI/OpenAPI-Specification
 [docs]: http://www.rubydoc.info/github/kevindew/openapi3_parser/Openapi3Parser/Nodes/Openapi
 
+## Installation
+
+You can install this gem into your bundler application by adding this line to
+your Gemfile:
+
+```
+gem "openapi3_parser", "~> 0.2.0"
+```
+
+and then running `$ bundle install`
+
+Or install the gem onto your machine via ` $ gem install openapi3_parser`
+
 ## Status
 
 This is currently a work in progress and will remain so until it reaches 1.0.

data/TODO.md

@@ -6,26 +6,29 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [ ] Refactor the various NodeFactory modules to be a less confusing
       hierachical structure. Consider having factories subclass instead of use
       mixin
-- [ ] Decouple Document class for the source file. Consider a source file class
+- [x] Decouple Document class for the source file. Consider a source file class
       instead
-- [ ] Validate that a reference creates the type of node that is expected in
+- [x] Validate that a reference creates the type of node that is expected in
       a context
-- [ ] Allow opening of references from additional files
-- [ ] Allow opening of openapi documents by URL
-- [ ] Support references by URL, consider option to limit behaviour
+- [x] Allow opening of references from additional files
+- [x] Allow opening of openapi documents by URL
+- [x] Support references by URL
+- [ ] Consider option to limit open by URL/path behaviour
 - [ ] Support converting CommonMark to HTML
 - [ ] 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
 - [ ] Publish documentation of the interface through the structure
-- [ ] Consider a resolved context class for representing context with a node
+- [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
 - [ ] Associate/resolve operation id / operation references
 - [ ] Do something to model expressions
-- [ ] Improve the modelling of namespace
+- [x] Improve the modelling of namespace
 - [ ] Set up nicer string representations of key classes to help them be
       debugged
-- [ ] Ensure Array and Map nodes return empty ones by default rather than nil
+- [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
+      or (potentially) a pointer class

data/lib/openapi3_parser.rb

@@ -1,52 +1,40 @@
 # frozen_string_literal: true
 
-require "openapi3_parser/error"
 require "openapi3_parser/document"
-
-require "yaml"
-require "json"
+require "openapi3_parser/source_input/raw"
+require "openapi3_parser/source_input/file"
+require "openapi3_parser/source_input/url"
 
 module Openapi3Parser
   # For a variety of inputs this will construct an OpenAPI document. For a
   # String/File input it will try to determine if the input is JSON or YAML.
   #
-  # @param [String, Hash, File] input Source for the OpenAPI document
+  # @param  [String, Hash, File]  input Source for the OpenAPI document
   #
   # @return [Document]
   def self.load(input)
-    # working_directory ||= if input.respond_to?(:read)
-    #                         File.dirname(input)
-    #                       else
-    #                         Dir.pwd
-    #                       end
-
-    Document.new(parse_input(input))
+    Document.new(SourceInput::Raw.new(input))
   end
 
   # For a given string filename this will read the file and parse it as an
   # OpenAPI document. It will try detect automatically whether the contents
   # are JSON or YAML.
   #
-  # @param [String] path Filename of the OpenAPI document
+  # @param  [String]  path  Filename of the OpenAPI document
   #
   # @return [Document]
   def self.load_file(path)
-    file = File.open(path)
-    load(file)
+    Document.new(SourceInput::File.new(path))
   end
 
-  def self.parse_input(input)
-    return input if input.respond_to?(:keys)
-
-    extension = input.respond_to?(:extname) ? input.extname : nil
-    contents = input.respond_to?(:read) ? input.read : input
-
-    if extension == ".json" || contents.strip[0] == "{"
-      JSON.parse(contents)
-    else
-      YAML.safe_load(contents, [], [], true)
-    end
+  # For a given string URL this will request the resource and parse it as an
+  # OpenAPI document. It will try detect automatically whether the contents
+  # are JSON or YAML.
+  #
+  # @param  [String]  url URL of the OpenAPI document
+  #
+  # @return [Document]
+  def self.load_url(url)
+    Document.new(SourceInput::Url.new(url.to_s))
   end
-
-  private_class_method :parse_input
 end

data/lib/openapi3_parser/context.rb

@@ -1,54 +1,112 @@
 # frozen_string_literal: true
 
+require "openapi3_parser/context/location"
+
 module Openapi3Parser
+  # Context is a construct used in both the node factories and the nodes
+  # themselves. It is used to represent the data, and the source of it, that
+  # a node is associated with. It also acts as a bridge between a node/node
+  # factory and associated document.
+  #
+  # @attr_reader                            input
+  # @attr_reader  [Context::Location]       document_location
+  # @attr_reader  [Context::Location, nil]  source_location
+  # @attr_reader  [Context, nil]            referenced_by
   class Context
-    attr_reader :input, :namespace, :document, :parent
+    # Create a context for the root of a document
+    # @return [Context]
+    def self.root(input, source)
+      location = Location.new(source, [])
+      new(input, document_location: location)
+    end
+
+    # Create a context for a field within the current contexts data
+    # eg for a context of:
+    #   root = Context.root({ "test" => {} }, source)
+    # we can get the context of "test" with:
+    #   test = Context.next_field(root, "test")
+    #
+    # @param  [Context] parent_context
+    # @param  [String]  field
+    # @return [Context]
+    def self.next_field(parent_context, field)
+      pc = parent_context
+      input = pc.input.respond_to?(:[]) ? pc.input[field] : nil
+      new(input,
+          document_location: Location.next_field(pc.document_location, field),
+          source_location: Location.next_field(pc.source_location, field),
+          referenced_by: pc.referenced_by)
+    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
+    #
+    # @param  [Context] referencer_context
+    # @param            input
+    # @param  [Source]  source
+    # @param  [::Array] pointer_segments
+    # @return [Context]
+    def self.reference_field(referencer_context,
+                             input:,
+                             source:,
+                             pointer_segments:)
+      new(input,
+          document_location: referencer_context.document_location,
+          source_location: Location.new(source, pointer_segments),
+          referenced_by: referencer_context)
+    end
+
+    attr_reader :input, :document_location, :source_location, :referenced_by
 
-    def initialize(input:, namespace: [], document:, parent: nil)
+    # @param                            input
+    # @param  [Context::Location]       document_location
+    # @param  [Context::Location, nil]  source_location
+    # @param  [Context, nil]            referenced_by
+    def initialize(input,
+                   document_location:,
+                   source_location: nil,
+                   referenced_by: nil)
       @input = input
-      @namespace = namespace.freeze
-      @document = document
-      @parent = parent
+      @document_location = document_location
+      @source_location = source_location || document_location
+      @referenced_by = referenced_by
     end
 
-    def self.root(input, document)
-      new(input: input, document: document)
+    # @return [Document]
+    def document
+      document_location.source.document
     end
 
-    def stringify_namespace
-      return "root" if namespace.empty?
-      namespace
-        .map { |i| i.to_s.include?("/") ? %("#{i}") : i }
-        .join("/")
+    # @return [Source]
+    def source
+      source_location.source
     end
 
-    def next_namespace(segment, next_input = nil)
-      next_input ||= input.nil? ? nil : input[segment]
-      self.class.new(
-        input: next_input,
-        namespace: namespace + [segment],
-        document: document,
-        parent: self
-      )
+    # @return [Source::ReferenceResolver]
+    def register_reference(reference, factory)
+      source.register_reference(reference, factory, self)
     end
 
-    def resolve_reference
-      document.resolve_reference(input["$ref"]) do |resolved_input, namespace|
-        # @TODO track reference for cyclic depenendies
-        next_context = resolved_reference(resolved_input, namespace)
-        yield(next_context)
-      end
+    # @deprecated
+    def namespace
+      document_location.pointer.segments
     end
 
-    private
+    def inspect
+      %{#{self.class.name}(document_location: #{document_location}, } +
+        %{source_location: #{source_location}), referenced_by: } +
+        %{#{referenced_by})}
+    end
+
+    def location_summary
+      summary = document_location.to_s
+      summary += " (#{source_location})" if document_location != source_location
+      summary
+    end
 
-    def resolved_reference(input, namespace)
-      self.class.new(
-        input: input,
-        namespace: namespace,
-        document: document,
-        parent: parent
-      )
+    def to_s
+      location_summary
     end
   end
 end

data/lib/openapi3_parser/context/location.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/context/pointer"
+
+module Openapi3Parser
+  class Context
+    # Class used to represent a location within an OpenAPI document.
+    # It contains a source, which is the source file/data used for the contents
+    # and the pointer which indicates where in the object like file the data is
+    class Location
+      def self.next_field(location, field)
+        new(location.source, location.pointer.segments + [field])
+      end
+
+      attr_reader :source, :pointer
+
+      # @param [Openapi3Parser::Source] source
+      # @param [::Array] pointer_segments
+      def initialize(source, pointer_segments)
+        @source = source
+        @pointer = Pointer.new(pointer_segments.freeze)
+      end
+
+      def ==(other)
+        source == other.source && pointer == other.pointer
+      end
+
+      def to_s
+        source.relative_to_root + pointer.fragment
+      end
+
+      def inspect
+        %{#{self.class.name}(source: #{source.inspect}, pointer: #{pointer})}
+      end
+    end
+  end
+end

data/lib/openapi3_parser/context/pointer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Openapi3Parser
+  class Context
+    # 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
+
+      # @param [::Array] segments
+      def initialize(segments)
+        @segments = segments.freeze
+      end
+
+      def ==(other)
+        segments == other.segments
+      end
+
+      def fragment
+        segments.map { |s| CGI.escape(s.to_s).gsub("+", "%20") }
+                .join("/")
+                .prepend("#/")
+      end
+
+      def to_s
+        fragment
+      end
+
+      def inspect
+        %{#{self.class.name}(segments: #{segments}, fragment: "#{fragment}")}
+      end
+    end
+  end
+end

data/lib/openapi3_parser/document.rb

@@ -1,48 +1,148 @@
 # frozen_string_literal: true
 
 require "openapi3_parser/context"
+require "openapi3_parser/document/reference_register"
 require "openapi3_parser/error"
 require "openapi3_parser/node_factories/openapi"
+require "openapi3_parser/source"
+require "openapi3_parser/validation/error_collection"
 
 require "forwardable"
 
 module Openapi3Parser
+  # Document is the root construct of a created OpenAPI Document and can be
+  # used to navigate the contents of a document or to check it's validity.
+  #
+  # @attr_reader  [Source] root_source
   class Document
     extend Forwardable
+    include Enumerable
 
-    attr_reader :input
+    attr_reader :root_source
 
-    def_delegators :factory, :valid?, :errors
+    # @!method valid?
+    #   Whether this OpenAPI document has any validation issues or not. See
+    #   #errors to access the errors
+    #
+    #   @return [Boolean]
+    def_delegator :factory, :valid?
+
+    # @!method openapi
+    #   The value of the openapi version field for this document
+    #   @see Nodes::Openapi#openapi
+    #   @return [String]
+    # @!method info
+    #   The value of the info field on the OpenAPI document
+    #   @see Nodes::Openapi#info
+    #   @return [Nodes::Info]
+    # @!method servers
+    #   The value of the servers field on the OpenAPI document
+    #   @see Nodes::Openapi#servers
+    #   @return [Nodes::Array<Nodes::Server>]
+    # @!method paths
+    #   The value of the paths field on the OpenAPI document
+    #   @see Nodes::Openapi#paths
+    #   @return [Nodes::Paths]
+    # @!method components
+    #   The value of the components field on the OpenAPI document
+    #   @see Nodes::Openapi#components
+    #   @return [Nodes::Components]
+    # @!method security
+    #   The value of the security field on the OpenAPI document
+    #   @see Nodes::Openapi#security
+    #   @return [Nodes::Array<Nodes::SecurityRequirement>]
+    # @!method tags
+    #   The value of the tags field on the OpenAPI document
+    #   @see Nodes::Openapi#tags
+    #   @return [Nodes::Array<Nodes::Tag>]
+    # @!method external_docs
+    #   The value of the external_docs field on the OpenAPI document
+    #   @see Nodes::Openapi#external_docs
+    #   @return [Nodes::ExternalDocumentation]
+    # @!method extension
+    #   Look up an extension field provided for the root object of the document
+    #   @see Node::Object#extension
+    #   @return [Hash, Array, Numeric, String, true, false, nil]
+    # @!method []
+    #   Look up an attribute on the root of the OpenAPI document by String
+    #   or Symbol
+    #   @see Node::Object#[]
+    #   @return Object
+    # @!method each
+    #   Iterate through the attributes of the root object
+    #   @see Node::Object#each
     def_delegators :root, :openapi, :info, :servers, :paths, :components,
                    :security, :tags, :external_docs, :extension, :[], :each
 
-    def initialize(input)
-      @input = input
+    # @param [SourceInput] source_input
+    def initialize(source_input)
+      @reference_register = ReferenceRegister.new
+      @root_source = Source.new(source_input, self, reference_register)
+      @build_in_progress = false
+      @built = false
     end
 
+    # @return [Nodes::Openapi]
     def root
       factory.node
     end
 
-    def resolve_reference(reference)
-      if reference[0..1] != "#/"
-        raise Error, "Only anchor references are currently supported"
-      end
+    # All the additional sources that have been referenced as part of loading
+    # the OpenAPI document
+    #
+    # @return [Array<Source>]
+    def reference_sources
+      build unless built
+      reference_register.sources
+    end
 
-      parts = reference.split("/").drop(1).map do |field|
-        CGI.unescape(field.gsub("+", "%20"))
-      end
+    # All of the sources involved in this OpenAPI document
+    #
+    # @return [Array<Source>]
+    def sources
+      [root_source] + reference_sources
+    end
 
-      result = input.dig(*parts)
-      raise Error, "Could not resolve reference #{reference}" unless result
+    # Any validation errors that are present on the OpenAPI document
+    #
+    # @return [Validation::ErrorCollection]
+    def errors
+      reference_factories.inject(factory.errors) do |memo, f|
+        Validation::ErrorCollection.combine(memo, f.errors)
+      end
+    end
 
-      yield(result, parts)
+    # Look up whether an instance of SourceInput is already a known source
+    # for this document.
+    #
+    # @param [SourceInput] source_input
+    # @return [Source, nil]
+    def source_for_source_input(source_input)
+      sources.find { |source| source.source_input == source_input }
     end
 
     private
 
+    attr_reader :reference_register, :built, :build_in_progress
+
+    def build
+      return if build_in_progress || built
+      @build_in_progress = true
+      context = Context.root(root_source.data, root_source)
+      @factory = NodeFactories::Openapi.new(context)
+      reference_register.freeze
+      @build_in_progress = false
+      @built = true
+    end
+
     def factory
-      @factory ||= NodeFactories::Openapi.new(Context.root(input, self))
+      build unless built
+      @factory
+    end
+
+    def reference_factories
+      build unless built
+      reference_register.factories
     end
   end
 end