openapi_contracts 0.8.0 → 0.9.0

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

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

@@ -0,0 +1,34 @@
+module OpenapiContracts::Parser::Transformers
+  class Pointer < Base
+    def call(object)
+      return unless object['$ref'].present?
+
+      object['$ref'] = transform_pointer(object['$ref'])
+    end
+
+    private
+
+    def transform_pointer(target)
+      if %r{^#/(?<pointer>.*)} =~ target
+        # A JSON Pointer
+        generate_absolute_pointer(pointer)
+      elsif %r{^(?<relpath>[^#]+)(?:#/(?<pointer>.*))?} =~ target
+        ptr = @parser.filenesting[@cwd.join(relpath)]
+        tgt = ptr.to_json_pointer
+        tgt += "/#{pointer}" if pointer
+        tgt
+      else
+        target
+      end
+    end
+
+    # A JSON pointer to the currently parsed file as seen from the root openapi file
+    def generate_absolute_pointer(json_pointer)
+      if @pointer.empty?
+        "#/#{json_pointer}"
+      else
+        "#{@pointer.to_json_pointer}/#{json_pointer}"
+      end
+    end
+  end
+end

data/lib/openapi_contracts/parser/transformers.rb

@@ -0,0 +1,5 @@
+module OpenapiContracts::Parser::Transformers
+  autoload :Base,     'openapi_contracts/parser/transformers/base'
+  autoload :Nullable, 'openapi_contracts/parser/transformers/nullable'
+  autoload :Pointer,  'openapi_contracts/parser/transformers/pointer'
+end

data/lib/openapi_contracts/parser.rb

@@ -0,0 +1,61 @@
+module OpenapiContracts
+  class Parser
+    autoload :Transformers, 'openapi_contracts/parser/transformers'
+
+    TRANSFORMERS = [Transformers::Nullable, Transformers::Pointer].freeze
+
+    def self.call(dir, filename)
+      new(dir.join(filename)).parse
+    end
+
+    attr_reader :filenesting, :rootfile
+
+    def initialize(rootfile)
+      @cwd = rootfile.parent
+      @rootfile = rootfile
+      @filenesting = {}
+    end
+
+    def parse
+      @filenesting = build_file_list
+      @filenesting.each_with_object({}) do |(path, pointer), schema|
+        target = pointer.to_a.reduce(schema) { |d, k| d[k] ||= {} }
+        target.delete('$ref') # ref file pointers must be replaced
+        target.merge! file_to_data(path, pointer)
+      end
+    end
+
+    private
+
+    def build_file_list
+      list = {@rootfile.relative_path_from(@cwd) => Doc::Pointer[]}
+      Dir[File.expand_path('components/**/*.yaml', @cwd)].each do |file|
+        pathname = Pathname(file).relative_path_from(@cwd)
+        pointer = Doc::Pointer.from_path pathname.sub_ext('')
+        list.merge! pathname => pointer
+      end
+      YAML.safe_load_file(@rootfile).fetch('paths') { {} }.each_pair do |k, v|
+        next unless v['$ref'] && !v['$ref'].start_with?('#')
+
+        list.merge! Pathname(v['$ref']) => Doc::Pointer['paths', k]
+      end
+      list
+    end
+
+    def file_to_data(pathname, pointer)
+      YAML.safe_load_file(@cwd.join(pathname)).tap do |data|
+        transform_objects!(data, pathname.parent, pointer)
+      end
+    end
+
+    def transform_objects!(object, cwd, pointer)
+      case object
+      when Hash
+        object.each_value { |v| transform_objects!(v, cwd, pointer) }
+        TRANSFORMERS.map { |t| t.new(self, cwd, pointer) }.each { |t| t.call(object) }
+      when Array
+        object.each { |o| transform_objects!(o, cwd, pointer) }
+      end
+    end
+  end
+end

data/lib/openapi_contracts/payload_parser.rb

@@ -0,0 +1,39 @@
+require 'singleton'
+
+module OpenapiContracts
+  class PayloadParser
+    include Singleton
+
+    class << self
+      delegate :parse, :register, to: :instance
+    end
+
+    Entry = Struct.new(:matcher, :parser) do
+      def call(raw)
+        parser.call(raw)
+      end
+
+      def match?(media_type)
+        matcher == media_type || matcher.match?(media_type)
+      end
+    end
+
+    def initialize
+      @parsers = []
+    end
+
+    def parse(media_type, payload)
+      parser = @parsers.find { |e| e.match?(media_type) }
+      raise ArgumentError, "#{media_type.inspect} is not supported yet" unless parser
+
+      parser.call(payload)
+    end
+
+    def register(matcher, parser)
+      @parsers << Entry.new(matcher, parser)
+    end
+  end
+
+  PayloadParser.register(%r{(/|\+)json$}, ->(raw) { JSON(raw) })
+  PayloadParser.register('application/x-www-form-urlencoded', ->(raw) { Rack::Utils.parse_nested_query(raw) })
+end

data/lib/openapi_contracts/rspec.rb

@@ -14,12 +14,12 @@ RSpec::Matchers.define :match_openapi_doc do |doc, options = {}| # rubocop:disab
   end
 
   description do
-    desc = 'to match the openapi schema'
+    desc = 'match the openapi schema'
     desc << " with #{http_status_desc(@status)}" if @status
     desc
   end
 
-  failure_message do |_reponse|
+  failure_message do |_response|
     @errors.map { |e| "* #{e}" }.join("\n")
   end
 

data/lib/openapi_contracts/validators/base.rb

@@ -22,7 +22,11 @@ module OpenapiContracts::Validators
 
     private
 
-    delegate :expected_status, :response, :spec, to: :@env
+    delegate :operation, :options, :request, :response, to: :@env
+
+    def response_desc
+      "#{request.request_method} #{request.path}"
+    end
 
     # :nocov:
     def validate

data/lib/openapi_contracts/validators/documented.rb

@@ -1,18 +1,25 @@
 module OpenapiContracts::Validators
+  # Purpose of this validator
+  # * ensure the operation is documented (combination http-method + path)
+  # * ensure the response-status is documented on the operation
   class Documented < Base
     self.final = true
 
     private
 
     def validate
-      return if spec
+      return operation_missing unless operation
 
-      status_desc = http_status_desc(response.status)
-      @errors << "Undocumented request/response for #{response_desc.inspect} with #{status_desc}"
+      response_missing unless operation.response_for_status(response.status)
+    end
+
+    def operation_missing
+      @errors << "Undocumented operation for #{response_desc.inspect}"
     end
 
-    def response_desc
-      "#{response.request.request_method} #{response.request.path}"
+    def response_missing
+      status_desc = http_status_desc(response.status)
+      @errors << "Undocumented response for #{response_desc.inspect} with #{status_desc}"
     end
   end
 end

data/lib/openapi_contracts/validators/headers.rb

@@ -2,6 +2,10 @@ module OpenapiContracts::Validators
   class Headers < Base
     private
 
+    def spec
+      @spec ||= operation.response_for_status(response.status)
+    end
+
     def validate
       spec.headers.each do |header|
         value = response.headers[header.name]

data/lib/openapi_contracts/validators/http_status.rb

@@ -5,13 +5,9 @@ module OpenapiContracts::Validators
     private
 
     def validate
-      return if expected_status.blank? || expected_status == response.status
+      return if options[:status] == response.status
 
-      @errors << "Response has #{http_status_desc}"
-    end
-
-    def http_status_desc
-      "http status #{Rack::Utils::HTTP_STATUS_CODES[response.status]} (#{response.status})"
+      @errors << "Response has #{http_status_desc(response.status)}"
     end
   end
 end

data/lib/openapi_contracts/validators/request_body.rb

@@ -0,0 +1,26 @@
+module OpenapiContracts::Validators
+  class RequestBody < Base
+    include SchemaValidation
+
+    private
+
+    delegate :media_type, to: :request
+    delegate :request_body, to: :operation
+
+    def data_for_validation
+      request.body.rewind
+      raw = request.body.read
+      OpenapiContracts::PayloadParser.parse(media_type, raw)
+    end
+
+    def validate
+      if !request_body
+        @errors << "Undocumented request body for #{response_desc.inspect}"
+      elsif !request_body.supports_media_type?(media_type)
+        @errors << "Undocumented request with media-type #{media_type.inspect}"
+      else
+        @errors += validate_schema(request_body.schema_for(media_type), data_for_validation)
+      end
+    end
+  end
+end

data/lib/openapi_contracts/validators/response_body.rb

@@ -0,0 +1,28 @@
+module OpenapiContracts::Validators
+  class ResponseBody < Base
+    include SchemaValidation
+
+    private
+
+    delegate :media_type, to: :response
+
+    def data_for_validation
+      # ActionDispatch::Response body is a plain string, while Rack::Response returns an array
+      OpenapiContracts::PayloadParser.parse(media_type, Array.wrap(response.body).join)
+    end
+
+    def spec
+      @spec ||= operation.response_for_status(response.status)
+    end
+
+    def validate
+      if spec.no_content?
+        @errors << 'Expected empty response body' if Array.wrap(response.body).any?(&:present?)
+      elsif !spec.supports_media_type?(media_type)
+        @errors << "Undocumented response with content-type #{media_type.inspect}"
+      else
+        @errors += validate_schema(spec.schema_for(media_type), data_for_validation)
+      end
+    end
+  end
+end

data/lib/openapi_contracts/validators/schema_validation.rb

@@ -0,0 +1,40 @@
+module OpenapiContracts::Validators
+  module SchemaValidation
+    module_function
+
+    def build_validation_schema(schema)
+      schema.raw.merge(
+        '$ref'    => schema.fragment,
+        '$schema' => schema_draft_version(schema)
+      )
+    end
+
+    def error_to_message(error)
+      pointer = " at #{error['data_pointer']}" if error['data_pointer'].present?
+      if error.key?('details')
+        error['details'].to_a.map { |(key, val)|
+          "#{key.humanize}: #{val}#{pointer}"
+        }.to_sentence
+      else
+        "#{error['data'].inspect}#{pointer} does not match the schema"
+      end
+    end
+
+    def schema_draft_version(schema)
+      if schema.openapi_version.blank? || schema.openapi_version < Gem::Version.new('3.1')
+        # Closest compatible version is actually draft 5 but not supported by json-schemer
+        'http://json-schema.org/draft-04/schema#'
+      else
+        # >= 3.1 is actually comptable with 2020-12 but not yet supported by json-schemer
+        'http://json-schema.org/draft-07/schema#'
+      end
+    end
+
+    def validate_schema(schema, data)
+      schemer = JSONSchemer.schema(build_validation_schema(schema))
+      schemer.validate(data).map do |err|
+        error_to_message(err)
+      end
+    end
+  end
+end

data/lib/openapi_contracts/validators.rb

@@ -1,16 +1,19 @@
 module OpenapiContracts
   module Validators
-    autoload :Base,       'openapi_contracts/validators/base'
-    autoload :Body,       'openapi_contracts/validators/body'
-    autoload :Documented, 'openapi_contracts/validators/documented'
-    autoload :Headers,    'openapi_contracts/validators/headers'
-    autoload :HttpStatus, 'openapi_contracts/validators/http_status'
+    autoload :Base,             'openapi_contracts/validators/base'
+    autoload :Documented,       'openapi_contracts/validators/documented'
+    autoload :Headers,          'openapi_contracts/validators/headers'
+    autoload :HttpStatus,       'openapi_contracts/validators/http_status'
+    autoload :RequestBody,      'openapi_contracts/validators/request_body'
+    autoload :ResponseBody,     'openapi_contracts/validators/response_body'
+    autoload :SchemaValidation, 'openapi_contracts/validators/schema_validation'
 
     # Defines order of matching
     ALL = [
       Documented,
       HttpStatus,
-      Body,
+      RequestBody,
+      ResponseBody,
       Headers
     ].freeze
   end

data/lib/openapi_contracts.rb

@@ -4,17 +4,22 @@ require 'active_support/core_ext/hash'
 require 'active_support/core_ext/class'
 require 'active_support/core_ext/module'
 require 'active_support/core_ext/string'
+require 'rubygems/version'
 
 require 'json_schemer'
+require 'rack'
 require 'yaml'
 
 module OpenapiContracts
-  autoload :Doc,        'openapi_contracts/doc'
-  autoload :Helper,     'openapi_contracts/helper'
-  autoload :Match,      'openapi_contracts/match'
-  autoload :Validators, 'openapi_contracts/validators'
+  autoload :Doc,             'openapi_contracts/doc'
+  autoload :Helper,          'openapi_contracts/helper'
+  autoload :Match,           'openapi_contracts/match'
+  autoload :OperationRouter, 'openapi_contracts/operation_router'
+  autoload :Parser,          'openapi_contracts/parser'
+  autoload :PayloadParser,   'openapi_contracts/payload_parser'
+  autoload :Validators,      'openapi_contracts/validators'
 
-  Env = Struct.new(:spec, :response, :expected_status)
+  Env = Struct.new(:operation, :options, :request, :response, keyword_init: true)
 
   module_function
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_contracts
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - mkon
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2023-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -36,42 +36,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.20
+        version: 1.0.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.20
+        version: 1.0.3
 - !ruby/object:Gem::Dependency
-  name: json_spec
+  name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.5
-  type: :development
+        version: 2.0.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.5
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
-  name: rack
+  name: json_spec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 1.1.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 1.1.5
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -92,14 +92,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.52.0
+        version: 1.54.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.52.0
+        version: 1.54.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -138,23 +138,33 @@ files:
 - README.md
 - lib/openapi_contracts.rb
 - lib/openapi_contracts/doc.rb
-- lib/openapi_contracts/doc/file_parser.rb
 - lib/openapi_contracts/doc/header.rb
-- lib/openapi_contracts/doc/method.rb
+- lib/openapi_contracts/doc/operation.rb
 - lib/openapi_contracts/doc/parameter.rb
-- lib/openapi_contracts/doc/parser.rb
 - lib/openapi_contracts/doc/path.rb
+- lib/openapi_contracts/doc/pointer.rb
+- lib/openapi_contracts/doc/request.rb
 - lib/openapi_contracts/doc/response.rb
 - lib/openapi_contracts/doc/schema.rb
+- lib/openapi_contracts/doc/with_parameters.rb
 - lib/openapi_contracts/helper.rb
 - lib/openapi_contracts/match.rb
+- lib/openapi_contracts/operation_router.rb
+- lib/openapi_contracts/parser.rb
+- lib/openapi_contracts/parser/transformers.rb
+- lib/openapi_contracts/parser/transformers/base.rb
+- lib/openapi_contracts/parser/transformers/nullable.rb
+- lib/openapi_contracts/parser/transformers/pointer.rb
+- lib/openapi_contracts/payload_parser.rb
 - lib/openapi_contracts/rspec.rb
 - lib/openapi_contracts/validators.rb
 - lib/openapi_contracts/validators/base.rb
-- lib/openapi_contracts/validators/body.rb
 - lib/openapi_contracts/validators/documented.rb
 - lib/openapi_contracts/validators/headers.rb
 - lib/openapi_contracts/validators/http_status.rb
+- lib/openapi_contracts/validators/request_body.rb
+- lib/openapi_contracts/validators/response_body.rb
+- lib/openapi_contracts/validators/schema_validation.rb
 homepage: https://github.com/mkon/openapi_contracts
 licenses:
 - MIT
@@ -168,7 +178,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
   - - "<"
     - !ruby/object:Gem::Version
       version: '3.3'