openapi_contracts 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6c02afb8cd5c3ad005ff169eb4c1294b8de98dd97c4cd643609a8f3a5cc66d5
-  data.tar.gz: e8808416c903da9662789d67da35fa6b2f44e9ba7659b7baa675ef5cdabbcd8a
+  metadata.gz: 6a6d176876364825de3b5e11746a49add3125a4511003e24002f8dda270347d6
+  data.tar.gz: 468ebb8a26dadc72b3f0d9fdb0e9a2f8a39b2e94418c555926fe0b12d0ea0b8a
 SHA512:
-  metadata.gz: 199fa68a93326277251d413ff5e6c3d2b4718b3345a74cb79f227252a4e741f4cb179f05eaa304b2807b29e64f5510a0c9f5bec817c9373337c68a7f8a1ba8d1
-  data.tar.gz: 81c16071342cf8203380e85ced5bf52974231371d269c72ea4d182b472148b4e801c12cc3ca699237643559c1a52dd935f9b984f73c974e51002061da8b3dfa3
+  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,48 +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 is especially important with
-dynamic paths.
 
-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. Then it does the following checks:
+It uses the `request.path`, `request.method`, `status` and `headers` on the test subject
+(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

@@ -0,0 +1,49 @@
+module OpenapiContracts
+  class Doc::Parameter
+    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 in_path?
+      @in == 'path'
+    end
+
+    def matches?(value)
+      case @spec.dig('schema', 'type')
+      when 'integer'
+        integer_parameter_matches?(value)
+      when 'number'
+        number_parameter_matches?(value)
+      else
+        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)
+
+      schemer.valid?(value.to_i)
+    end
+
+    def number_parameter_matches?(value)
+      return false unless /^-?(\d+\.)?\d+$/.match?(value)
+
+      schemer.valid?(value.to_f)
+    end
+  end
+end

data/lib/openapi_contracts/doc/path.rb

@@ -1,26 +1,46 @@
 module OpenapiContracts
   class Doc::Path
-    def initialize(schema)
-      @schema = schema
+    include Doc::WithParameters
 
-      @methods = (known_http_methods & @schema.keys).to_h do |method|
-        [method, Doc::Method.new(@schema.navigate(method))]
+    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 operations
+      @supported_methods.each.lazy.map { |m| Doc::Operation.new(self, @spec.navigate(m)) }
+    end
+
+    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 methods
-      @methods.each_value
+    def static?
+      !dynamic?
     end
 
-    def with_method(method)
-      @methods[method]
+    def supports_method?(method)
+      @supported_methods.include?(method)
     end
 
-    private
+    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,12 +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 :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)
@@ -14,11 +16,12 @@ 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(@schema.at_pointer(['paths', path]))]
+        [path, Path.new(path, @schema.at_pointer(Doc::Pointer['paths', path]))]
       end
+      @dynamic_paths = paths.select(&:dynamic?)
     end
 
     # Returns an Enumerator over all paths
@@ -26,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
@@ -35,8 +38,8 @@ 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

data/lib/openapi_contracts/match.rb

@@ -1,11 +1,18 @@
 module OpenapiContracts
   class Match
+    DEFAULT_OPTIONS = {request_body: false}.freeze
+    MIN_REQUEST_ANCESTORS = %w(Rack::Request::Env Rack::Request::Helpers).freeze
+    MIN_RESPONSE_ANCESTORS = %w(Rack::Response::Helpers).freeze
+
     attr_reader :errors
 
     def initialize(doc, response, options = {})
       @doc = doc
       @response = response
-      @options = options
+      @request = options.delete(:request) { response.request }
+      @options = DEFAULT_OPTIONS.merge(options)
+      raise ArgumentError, "#{@response} must be compatible with Rack::Response::Helpers" unless response_compatible?
+      raise ArgumentError, "#{@request} must be compatible with Rack::Request::{Env,Helpers}" unless request_compatible?
     end
 
     def valid?
@@ -17,18 +24,35 @@ module OpenapiContracts
 
     private
 
-    def lookup_api_spec
-      @doc.response_for(
-        @options.fetch(:path, @response.request.path),
-        @response.request.request_method.downcase,
-        @response.status.to_s
+    def matchers
+      env = Env.new(
+        options:   @options,
+        operation: operation,
+        request:   @request,
+        response:  @response
       )
+      validators = Validators::ALL.dup
+      validators.delete(Validators::HttpStatus) unless @options[:status]
+      validators.delete(Validators::RequestBody) unless @options[:request_body]
+      validators.reverse
+                .reduce(->(err) { err }) { |s, m| m.new(s, env) }
     end
 
-    def matchers
-      env = Env.new(lookup_api_spec, @response, @options[:status])
-      Validators::ALL.reverse
-                     .reduce(->(err) { err }) { |s, m| m.new(s, env) }
+    def operation
+      @doc.operation_for(
+        @options.fetch(:path, @request.path),
+        @request.request_method.downcase
+      )
+    end
+
+    def request_compatible?
+      ancestors = @request.class.ancestors.map(&:to_s)
+      MIN_REQUEST_ANCESTORS.all? { |s| ancestors.include?(s) }
+    end
+
+    def response_compatible?
+      ancestors = @response.class.ancestors.map(&:to_s)
+      MIN_RESPONSE_ANCESTORS.all? { |s| ancestors.include?(s) }
     end
   end
 end

data/lib/openapi_contracts/operation_router.rb

@@ -0,0 +1,33 @@
+module OpenapiContracts
+  class OperationRouter
+    def initialize(doc)
+      @doc = doc
+      @dynamic_paths = doc.paths.select(&:dynamic?)
+    end
+
+    def route(actual_path, method)
+      @doc.with_path(actual_path)&.then { |p| return p.with_method(method) }
+
+      @dynamic_paths.each do |path|
+        next unless path.supports_method?(method)
+        next unless m = path.path_regexp.match(actual_path)
+
+        operation = path.with_method(method)
+        parameters = (path.parameters + operation.parameters).select(&:in_path?)
+
+        return operation if parameter_match?(m.named_captures, parameters)
+      end
+
+      nil
+    end
+
+    private
+
+    def parameter_match?(actual_params, parameters)
+      actual_params.each do |k, v|
+        return false unless parameters&.find { |s| s.name == k }&.matches?(v)
+      end
+      true
+    end
+  end
+end

data/lib/openapi_contracts/parser/transformers/base.rb

@@ -0,0 +1,15 @@
+module OpenapiContracts::Parser::Transformers
+  class Base
+    def initialize(parser, cwd, pointer)
+      @parser = parser
+      @cwd = cwd
+      @pointer = pointer
+    end
+
+    # :nocov:
+    def call
+      raise NotImplementedError
+    end
+    # :nocov:
+  end
+end

data/lib/openapi_contracts/parser/transformers/nullable.rb

@@ -0,0 +1,10 @@
+module OpenapiContracts::Parser::Transformers
+  class Nullable < Base
+    def call(object)
+      return unless object['type'].present? && object['nullable'] == true
+
+      object.delete('nullable')
+      object['type'] = [object['type'], 'null']
+    end
+  end
+end