openapi_contracts 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25a37c81bfa9cb9d1d26f26a25b7c81f0675a153c199223639bdd48c76537cb6
-  data.tar.gz: 48529ed541f4ad72568d222d2a57e30ef7f1a7b5e59fbb447961a58d57eafe26
+  metadata.gz: 6a6d176876364825de3b5e11746a49add3125a4511003e24002f8dda270347d6
+  data.tar.gz: 468ebb8a26dadc72b3f0d9fdb0e9a2f8a39b2e94418c555926fe0b12d0ea0b8a
 SHA512:
-  metadata.gz: 1cc4ee62cea4e015834ae6a493bc771f13670b553cfdc1085b7dac79ea5a347583786ec4cd1db31c9054d88a010dd5d779c64f13df4388a3f55a3eae07ef577a
-  data.tar.gz: 9991124beb074d92107b1026e6ffd529cca988d8154eac6c6cc92aa5103df5de11cf917d1809545e26810de07959202f295a5d23a1a15077e639d2212bbc6286
+  metadata.gz: c310ffa9c64a85d3cef12f2e2fa685ae52f0bfeff975ab63a1532f88be964dc2acd577b24f4a70017efb0bc4b19c0a522a56b9660686ba33c89d970959ca1690
+  data.tar.gz: 1a2293a48671a21d6f6915162c1240fa56b719e2d40947b8e46782635c6cc6cd7d4e26ee6012f7360b098d1ab04bf82f282e090fb373d9e1e9ddb982a6672dce

data/README.md

@@ -4,24 +4,24 @@
 [![Gem Version](https://badge.fury.io/rb/openapi_contracts.svg)](https://badge.fury.io/rb/openapi_contracts)
 [![Depfu](https://badges.depfu.com/badges/8ac57411497df02584bbf59685634e45/overview.svg)](https://depfu.com/github/mkon/openapi_contracts?project_id=35354)
 
-Use openapi documentation as an api contract.
+Use OpenAPI documentation as an API contract.
 
 Currently supports OpenAPI documentation in the structure as used by [Redocly](https://github.com/Redocly/create-openapi-repo), but should also work for single file schemas.
 
-Adds RSpec matchers to easily verify that your responses match the OpenAPI documentation.
+Adds RSpec matchers to easily verify that your requests and responses match the OpenAPI documentation.
 
 ## Usage
 
-First parse your api documentation:
+First, parse your API documentation:
 
 ```ruby
-# This must point to the folder where the "openapi.yaml" file is
-$doc = OpenapiContracts::Doc.parse(Rails.root.join('spec/fixtures/openapi/api-docs/openapi'))
+# This must point to the folder where the OAS file is stored
+$doc = OpenapiContracts::Doc.parse(Rails.root.join('spec/fixtures/openapi/api-docs'), '<filename>')
 ```
 
-Ideally you do this once in a RSpec `before(:suite)` hook.
+In case the `filename` argument is not set, parser will by default search for the file named `openapi.yaml`.
 
-Then you can use these matchers in your request specs:
+Ideally you do this once in an RSpec `before(:suite)` hook. Then you can use these matchers in your request specs:
 
 ```ruby
 subject { make_request and response }
@@ -34,51 +34,72 @@ it { is_expected.to match_openapi_doc($doc) }
 You can assert a specific http status to make sure the response is of the right status:
 
 ```ruby
-it { is_expected.to match_openapi_doc($api_doc).with_http_status(:ok) }
+it { is_expected.to match_openapi_doc($doc).with_http_status(:ok) }
 
-# this is equal to
+# This is equal to
 it 'responds with 200 and matches the doc' do
   expect(subject).to have_http_status(:ok)
-  expect(subject).to match_openapi_doc($api_doc)
-}
+  expect(subject).to match_openapi_doc($doc)
+end
 ```
 
 ### Options
 
 The `match_openapi_doc($doc)` method allows passing options as a 2nd argument.
-This allows overriding the default request.path lookup in case this does not find
-the correct response definition in your schema. This can be usefull when there is
-dynamic parameters in the path and the matcher fails to resolve the request path to
-an endpoint in the openapi specification.
 
-Example:
+* `path` allows overriding the default `request.path` lookup in case it does not find the
+  correct response definition in your schema. This is especially important when there are
+  dynamic parameters in the path and the matcher fails to resolve the request path to
+  an endpoint in the OAS file.
 
 ```ruby
-it { is_expected.to match_openapi_doc($api_doc, path: '/messages/{id}').with_http_status(:ok) }
+it { is_expected.to match_openapi_doc($doc, path: '/messages/{id}').with_http_status(:ok) }
 ```
 
+* `request_body` can be set to `true` in case the validation of the request body against the OpenAPI _requestBody_ schema is required.
+
+```ruby
+it { is_expected.to match_openapi_doc($doc, request_body: true).with_http_status(:created) }
+```
+
+Both options can as well be used simultaneously.
+
 ### Without RSpec
 
 You can also use the Validator directly:
+
 ```ruby
 # Let's raise an error if the response does not match
 result = OpenapiContracts.match($doc, response, options = {})
 raise result.errors.merge("/n") unless result.valid?
 ```
 
-### How it works
+## How it works
 
 It uses the `request.path`, `request.method`, `status` and `headers` on the test subject
-(which must be the response) to find the response schema in the OpenAPI document.
+(which must be the response) to find the request and response schemas in the OpenAPI document.
 Then it does the following checks:
 
 * The response is documented
 * Required headers are present
 * Documented headers match the schema (via json_schemer)
 * The response body matches the schema (via json_schemer)
+* The request body matches the schema (via json_schemer) - if `request_body: true`
+
+## Known Issues
+
+### OpenApi 3.0
+
+For openapi schemas < 3.1, data is  validated using JSON Schema Draft 04, even tho OpenApi 3.0 is a super+subset of Draft 05.
+This is due to the fact that we validate the data using json-schemer which does not support 05 and even then would not be fully compatible.
+However compatibility issues should be fairly rare and there might be workarounds by describing the data slightly different.
+
+### OpenAPi 3.1
+
+Here exists a similar problem. OpenApi 3.1 is finally fully compatible with JSON Draft 2020-12, but there is no support yet in json-schemer,
+so we use the closest draft which is 07. 
 
 ## Future plans
 
-* Validate sent requests against the request schema
 * Validate Webmock stubs against the OpenAPI doc
 * Generate example payloads from the OpenAPI doc

data/lib/openapi_contracts/doc/operation.rb

@@ -0,0 +1,27 @@
+module OpenapiContracts
+  class Doc::Operation
+    include Doc::WithParameters
+
+    def initialize(path, spec)
+      @path = path
+      @spec = spec
+      @responses = spec.navigate('responses').each.to_h do |status, subspec| # rubocop:disable Style/HashTransformValues
+        [status, Doc::Response.new(subspec)]
+      end
+    end
+
+    def request_body
+      return @request_body if instance_variable_defined?(:@request_body)
+
+      @request_body = @spec.navigate('requestBody')&.then { |s| Doc::Request.new(s) }
+    end
+
+    def responses
+      @responses.each_value
+    end
+
+    def response_for_status(status)
+      @responses[status.to_s]
+    end
+  end
+end

data/lib/openapi_contracts/doc/parameter.rb

@@ -1,86 +1,49 @@
 module OpenapiContracts
   class Doc::Parameter
-    attr_reader :schema
+    attr_reader :name, :in, :schema
+
+    def initialize(spec)
+      @spec = spec
+      options = spec.to_h
+      @name = options['name']
+      @in = options['in']
+      @required = options['required']
+    end
 
-    def initialize(options)
-      @name = options[:name]
-      @in = options[:in]
-      @required = options[:required]
-      @schema = options[:schema]
+    def in_path?
+      @in == 'path'
     end
 
     def matches?(value)
-      case schema['type']
+      case @spec.dig('schema', 'type')
       when 'integer'
         integer_parameter_matches?(value)
       when 'number'
         number_parameter_matches?(value)
-      when 'string'
-        string_parameter_matches?(value)
       else
-        # Not yet implemented
-        false
+        schemer.valid?(value)
       end
     end
 
     private
 
+    def schemer
+      @schemer ||= begin
+        schema = @spec.navigate('schema')
+        JSONSchemer.schema(Validators::SchemaValidation.build_validation_schema(schema))
+      end
+    end
+
     def integer_parameter_matches?(value)
       return false unless /^-?\d+$/.match?(value)
 
-      parsed = value.to_i
-      return false unless minimum_number_matches?(parsed)
-      return false unless maximum_number_matches?(parsed)
-
-      true
+      schemer.valid?(value.to_i)
     end
 
     def number_parameter_matches?(value)
       return false unless /^-?(\d+\.)?\d+$/.match?(value)
 
-      parsed = value.to_f
-      return false unless minimum_number_matches?(parsed)
-      return false unless maximum_number_matches?(parsed)
-
-      true
-    end
-
-    def minimum_number_matches?(value)
-      if (min = schema['minimum'])
-        if schema['exclusiveMinimum']
-          return false if value <= min
-        elsif value < min
-          return false
-        end
-      end
-      true
-    end
-
-    def maximum_number_matches?(value)
-      if (max = schema['maximum'])
-        if schema['exclusiveMaximum']
-          return false if value >= max
-        elsif value > max
-          return false
-        end
-      end
-      true
-    end
-
-    def string_parameter_matches?(value)
-      if (pat = schema['pattern'])
-        Regexp.new(pat).match?(value)
-      else
-        if (min = schema['minLength']) && (value.length < min)
-          return false
-        end
-
-        if (max = schema['maxLength']) && (value.length > max)
-          return false
-        end
-
-        true
-      end
+      schemer.valid?(value.to_f)
     end
   end
 end

data/lib/openapi_contracts/doc/path.rb

@@ -1,61 +1,46 @@
 module OpenapiContracts
   class Doc::Path
-    def initialize(path, schema)
-      @path = path
-      @schema = schema
+    include Doc::WithParameters
 
-      @methods = (known_http_methods & @schema.keys).to_h do |method|
-        [method, Doc::Method.new(@schema.navigate(method))]
-      end
+    HTTP_METHODS = %w(get head post put delete connect options trace patch).freeze
+
+    attr_reader :path
+
+    def initialize(path, spec)
+      @path = path
+      @spec = spec
+      @supported_methods = HTTP_METHODS & @spec.keys
     end
 
     def dynamic?
       @path.include?('{')
     end
 
-    def matches?(path)
-      @path == path || regexp_path.match(path) do |m|
-        m.named_captures.each do |k, v|
-          return false unless parameter_matches?(k, v)
-        end
-        true
-      end
+    def operations
+      @supported_methods.each.lazy.map { |m| Doc::Operation.new(self, @spec.navigate(m)) }
     end
 
-    def methods
-      @methods.each_value
+    def path_regexp
+      @path_regexp ||= begin
+        re = /\{(\S+)\}/
+        @path.gsub(re) { |placeholder|
+          placeholder.match(re) { |m| "(?<#{m[1]}>[^/]*)" }
+        }.then { |str| Regexp.new(str) }
+      end
     end
 
     def static?
       !dynamic?
     end
 
-    def with_method(method)
-      @methods[method]
+    def supports_method?(method)
+      @supported_methods.include?(method)
     end
 
-    private
-
-    def parameter_matches?(name, value)
-      parameter = @schema['parameters']
-        &.find { |p| p['name'] == name && p['in'] == 'path' }
-        &.then { |s| Doc::Parameter.new(s.with_indifferent_access) }
-
-      return false unless parameter
-
-      parameter.matches?(value)
-    end
-
-    def regexp_path
-      re = /\{(\S+)\}/
-      @path.gsub(re) { |placeholder|
-        placeholder.match(re) { |m| "(?<#{m[1]}>[^/]*)" }
-      }.then { |str| Regexp.new(str) }
-    end
+    def with_method(method)
+      return unless supports_method?(method)
 
-    def known_http_methods
-      # https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
-      %w(get head post put delete connect options trace patch).freeze
+      Doc::Operation.new(self, @spec.navigate(method))
     end
   end
 end

data/lib/openapi_contracts/doc/pointer.rb

@@ -0,0 +1,81 @@
+module OpenapiContracts
+  class Doc::Pointer
+    def self.[](*segments)
+      new Array.wrap(segments).flatten
+    end
+
+    def self.from_json_pointer(str)
+      raise ArguementError unless %r{^#/(?<pointer>.*)} =~ str
+
+      new(pointer.split('/').map { |s| s.gsub('~1', '/') })
+    end
+
+    def self.from_path(pathname)
+      new pathname.to_s.split('/')
+    end
+
+    def initialize(segments)
+      @segments = segments
+    end
+
+    def inspect
+      "<#{self.class.name}#{to_a}>"
+    end
+
+    delegate :empty?, to: :@segments
+
+    def navigate(*segments)
+      self.class[to_a + segments]
+    end
+
+    def parent
+      self.class[to_a[0..-2]]
+    end
+
+    def to_a
+      @segments
+    end
+
+    def to_json_pointer
+      escaped_segments.join('/').then { |s| "#/#{s}" }
+    end
+
+    def to_json_schemer_pointer
+      www_escaped_segments.join('/').then { |s| "#/#{s}" }
+    end
+
+    def walk(object)
+      return object if empty?
+
+      @segments.inject(object) do |obj, key|
+        return nil unless obj
+
+        if obj.is_a?(Array)
+          raise ArgumentError unless /^\d+$/ =~ key
+
+          key = key.to_i
+        end
+
+        obj[key]
+      end
+    end
+
+    def ==(other)
+      to_a == other.to_a
+    end
+
+    private
+
+    def escaped_segments
+      @segments.map do |s|
+        s.gsub(%r{/}, '~1')
+      end
+    end
+
+    def www_escaped_segments
+      escaped_segments.map do |s|
+        URI.encode_www_form_component(s)
+      end
+    end
+  end
+end

data/lib/openapi_contracts/doc/request.rb

@@ -0,0 +1,17 @@
+module OpenapiContracts
+  class Doc::Request
+    def initialize(schema)
+      @schema = schema.follow_refs
+    end
+
+    def schema_for(media_type)
+      return unless supports_media_type?(media_type)
+
+      @schema.navigate('content', media_type, 'schema')
+    end
+
+    def supports_media_type?(media_type)
+      @schema.dig('content', media_type).present?
+    end
+  end
+end

data/lib/openapi_contracts/doc/response.rb

@@ -12,18 +12,18 @@ module OpenapiContracts
       end
     end
 
-    def schema_for(content_type)
-      return unless supports_content_type?(content_type)
+    def schema_for(media_type)
+      return unless supports_media_type?(media_type)
 
-      @schema.navigate('content', content_type, 'schema')
+      @schema.navigate('content', media_type, 'schema')
     end
 
     def no_content?
       !@schema.key? 'content'
     end
 
-    def supports_content_type?(content_type)
-      @schema.dig('content', content_type).present?
+    def supports_media_type?(media_type)
+      @schema.dig('content', media_type).present?
     end
   end
 end

data/lib/openapi_contracts/doc/schema.rb

@@ -6,16 +6,47 @@ module OpenapiContracts
   class Doc::Schema
     attr_reader :pointer, :raw
 
-    def initialize(raw, pointer = nil)
+    def initialize(raw, pointer = Doc::Pointer[])
+      raise ArgumentError unless pointer.is_a?(Doc::Pointer)
+
       @raw = raw
       @pointer = pointer.freeze
     end
 
+    def each # rubocop:disable Metrics/MethodLength
+      data = resolve
+      case data
+      when Array
+        enum = data.each_with_index
+        Enumerator.new(enum.size) do |yielder|
+          loop do
+            _item, index = enum.next
+            yielder << navigate(index.to_s)
+          end
+        end
+      when Hash
+        enum = data.each_key
+        Enumerator.new(enum.size) do |yielder|
+          loop do
+            key = enum.next
+            yielder << [key, navigate(key)]
+          end
+        end
+      end
+    end
+
+    # :nocov:
+    def inspect
+      "<#{self.class.name} @pointer=#{@pointer.inspect}>"
+    end
+    # :nocov:
+
     # 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 = as_h['$ref'])
-        at_pointer(ref.split('/')[1..])
+      data = resolve
+      if data.is_a?(Hash) && data.key?('$ref')
+        at_pointer Doc::Pointer.from_json_pointer(data['$ref'])
       else
         self
       end
@@ -23,23 +54,26 @@ module OpenapiContracts
 
     # Generates a fragment pointer for the current schema path
     def fragment
-      pointer.map { |p| p.gsub('/', '~1') }.join('/').then { |s| "#/#{s}" }
+      pointer.to_json_schemer_pointer
     end
 
-    delegate :dig, :fetch, :keys, :key?, :[], :to_h, to: :as_h
+    delegate :dig, :fetch, :keys, :key?, :[], :to_h, to: :resolve
 
     def at_pointer(pointer)
       self.class.new(raw, pointer)
     end
 
-    def as_h
-      return @raw if pointer.nil? || pointer.empty?
+    def openapi_version
+      @raw['openapi']&.then { |v| Gem::Version.new(v) }
+    end
 
-      @raw.dig(*pointer)
+    # Returns the actual sub-specification contents at the pointer of this Specification
+    def resolve
+      @pointer.walk(@raw)
     end
 
-    def navigate(*spointer)
-      self.class.new(@raw, (pointer + Array.wrap(spointer)))
+    def navigate(*segments)
+      self.class.new(@raw, pointer.navigate(segments)).follow_refs
     end
   end
 end

data/lib/openapi_contracts/doc/with_parameters.rb

@@ -0,0 +1,9 @@
+module OpenapiContracts
+  class Doc
+    module WithParameters
+      def parameters
+        @parameters ||= Array.wrap(@spec.navigate('parameters')&.each&.map { |s| Doc::Parameter.new(s) })
+      end
+    end
+  end
+end

data/lib/openapi_contracts/doc.rb

@@ -1,13 +1,14 @@
 module OpenapiContracts
   class Doc
-    autoload :Header,     'openapi_contracts/doc/header'
-    autoload :FileParser, 'openapi_contracts/doc/file_parser'
-    autoload :Method,     'openapi_contracts/doc/method'
-    autoload :Parser,     'openapi_contracts/doc/parser'
-    autoload :Parameter,  'openapi_contracts/doc/parameter'
-    autoload :Path,       'openapi_contracts/doc/path'
-    autoload :Response,   'openapi_contracts/doc/response'
-    autoload :Schema,     'openapi_contracts/doc/schema'
+    autoload :Header,         'openapi_contracts/doc/header'
+    autoload :Operation,      'openapi_contracts/doc/operation'
+    autoload :Parameter,      'openapi_contracts/doc/parameter'
+    autoload :Path,           'openapi_contracts/doc/path'
+    autoload :Pointer,        'openapi_contracts/doc/pointer'
+    autoload :Request,        'openapi_contracts/doc/request'
+    autoload :Response,       'openapi_contracts/doc/response'
+    autoload :Schema,         'openapi_contracts/doc/schema'
+    autoload :WithParameters, 'openapi_contracts/doc/with_parameters'
 
     def self.parse(dir, filename = 'openapi.yaml')
       new Parser.call(dir, filename)
@@ -15,10 +16,10 @@ module OpenapiContracts
 
     attr_reader :schema
 
-    def initialize(schema)
-      @schema = Schema.new(schema)
+    def initialize(raw)
+      @schema = Schema.new(raw)
       @paths = @schema['paths'].to_h do |path, _|
-        [path, Path.new(path, @schema.at_pointer(['paths', path]))]
+        [path, Path.new(path, @schema.at_pointer(Doc::Pointer['paths', path]))]
       end
       @dynamic_paths = paths.select(&:dynamic?)
     end
@@ -28,8 +29,8 @@ module OpenapiContracts
       @paths.each_value
     end
 
-    def response_for(path, method, status)
-      with_path(path)&.with_method(method)&.with_status(status)
+    def operation_for(path, method)
+      OperationRouter.new(self).route(path, method.downcase)
     end
 
     # Returns an Enumerator over all Responses
@@ -37,18 +38,14 @@ module OpenapiContracts
       return enum_for(:responses) unless block_given?
 
       paths.each do |path|
-        path.methods.each do |method|
-          method.responses.each(&block)
+        path.operations.each do |operation|
+          operation.responses.each(&block)
         end
       end
     end
 
     def with_path(path)
-      if @paths.key?(path)
-        @paths[path]
-      else
-        @dynamic_paths.find { |p| p.matches?(path) }
-      end
+      @paths[path]
     end
   end
 end