Improved schema Parsing (#43)

* Add comments

* Extended models to return identical Response objects

* Rename path to pointer

* Rename schema to raw

lib/openapi_contracts/doc.rb

@@ -1,25 +1,47 @@
 module OpenapiContracts
   class Doc
     autoload :Header,   'openapi_contracts/doc/header'
+    autoload :Method,   'openapi_contracts/doc/method'
     autoload :Parser,   'openapi_contracts/doc/parser'
+    autoload :Path,     'openapi_contracts/doc/path'
     autoload :Response, 'openapi_contracts/doc/response'
     autoload :Schema,   'openapi_contracts/doc/schema'
 
     def self.parse(dir, filename = 'openapi.yaml')
       new Parser.call(dir, filename)
     end
 
+    attr_reader :schema
+
     def initialize(schema)
       @schema = Schema.new(schema)
+      @paths = @schema['paths'].to_h do |path, _|
+        [path, Path.new(@schema.at_pointer(['paths', path]))]
+      end
     end
 
-    delegate :dig, :fetch, :[], :at_path, to: :@schema
+    # Returns an Enumerator over all paths
+    def paths
+      @paths.each_value
+    end
 
     def response_for(path, method, status)
-      path = ['paths', path, method, 'responses', status]
-      return unless dig(*path).present?
+      with_path(path)&.with_method(method)&.with_status(status)
+    end
+
+    # Returns an Enumerator over all Responses
+    def responses(&block)
+      return enum_for(:responses) unless block_given?
+
+      paths.each do |path|
+        path.methods.each do |method|
+          method.responses.each(&block)
+        end
+      end
+    end
 
-      Response.new(@schema.at_path(path))
+    def with_path(path)
+      @paths[path]
     end
   end
 end

lib/openapi_contracts/doc/method.rb

@@ -0,0 +1,18 @@
+module OpenapiContracts
+  class Doc::Method
+    def initialize(schema)
+      @schema = schema
+      @responses = schema['responses'].to_h do |status, _|
+        [status, Doc::Response.new(schema.navigate('responses', status))]
+      end
+    end
+
+    def responses
+      @responses.each_value
+    end
+
+    def with_status(status)
+      @responses[status]
+    end
+  end
+end

lib/openapi_contracts/doc/path.rb

@@ -0,0 +1,18 @@
+module OpenapiContracts
+  class Doc::Path
+    def initialize(schema)
+      @schema = schema
+      @methods = @schema.to_h do |method, _|
+        [method, Doc::Method.new(@schema.navigate(method))]
+      end
+    end
+
+    def methods
+      @methods.each_value
+    end
+
+    def with_method(method)
+      @methods[method]
+    end
+  end
+end

lib/openapi_contracts/doc/schema.rb

@@ -1,38 +1,45 @@
 module OpenapiContracts
+  # Represents a part or the whole schema
+  # Generally even parts of the schema contain the whole schema, but store the pointer to
+  # their position in the overall schema. This allows even small sub-schemas to resolve
+  # links to any other part of the schema
   class Doc::Schema
-    attr_reader :path, :schema
+    attr_reader :pointer, :raw
 
-    def initialize(schema, path = nil)
-      @schema = schema
-      @path = path.freeze
+    def initialize(raw, pointer = nil)
+      @raw = raw
+      @pointer = pointer.freeze
     end
 
+    # Resolves Schema ref pointers links like "$ref: #/some/path" and returns new sub-schema
+    # at the target if the current schema is only a ref link.
     def follow_refs
-      if (ref = dig('$ref'))
-        at_path(ref.split('/')[1..])
+      if (ref = as_h['$ref'])
+        at_pointer(ref.split('/')[1..])
       else
         self
       end
     end
 
+    # Generates a fragment pointer for the current schema path
     def fragment
-      path.map { |p| p.gsub('/', '~1') }.join('/').then { |s| "#/#{s}" }
+      pointer.map { |p| p.gsub('/', '~1') }.join('/').then { |s| "#/#{s}" }
     end
 
-    delegate :dig, :fetch, :key?, :[], to: :to_h
+    delegate :dig, :fetch, :key?, :[], :to_h, to: :as_h
 
-    def at_path(path)
-      self.class.new(schema, path)
+    def at_pointer(pointer)
+      self.class.new(raw, pointer)
     end
 
-    def to_h
-      return @schema if path.nil? || path.empty?
+    def as_h
+      return @raw if pointer.nil? || pointer.empty?
 
-      @schema.dig(*path)
+      @raw.dig(*pointer)
     end
 
-    def navigate(*sub_path)
-      self.class.new(schema, (path + Array.wrap(sub_path)))
+    def navigate(*spointer)
+      self.class.new(@raw, (pointer + Array.wrap(spointer)))
     end
   end
 end

lib/openapi_contracts/validators/body.rb

@@ -14,7 +14,8 @@ def validate
 
     def validate_schema
       schema = spec.schema_for(response_content_type)
-      schemer = JSONSchemer.schema(schema.schema.merge('$ref' => schema.fragment))
+      # Trick JSONSchemer into validating only against the response schema
+      schemer = JSONSchemer.schema(schema.raw.merge('$ref' => schema.fragment))
       schemer.validate(JSON(response.body)).each do |err|
         @errors << error_to_message(err)
       end

spec/openapi_contracts/doc_spec.rb

@@ -15,20 +15,6 @@
     end
   end
 
-  describe '#at_path' do
-    subject { doc.at_path(pointer) }
-
-    let(:pointer) { %w(components schemas User) }
-
-    it 'is a correctly initialized schema' do
-      expect(subject).to be_a(OpenapiContracts::Doc::Schema)
-      hash = subject.to_h
-      expect(hash).to be_a(Hash)
-      expect(hash['type']).to eq 'object'
-      expect(hash.dig('properties', 'attributes', 'required')).to eq %w(name email)
-    end
-  end
-
   describe '#response_for' do
     subject { doc.response_for(path, method, status) }
 
@@ -38,4 +24,12 @@
 
     it { is_expected.to be_a(OpenapiContracts::Doc::Response) }
   end
+
+  describe '#responses' do
+    subject { doc.responses }
+
+    it { is_expected.to all be_a(OpenapiContracts::Doc::Response) }
+
+    it { is_expected.to have_attributes(count: 7) }
+  end
 end