openapi_contracts 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a6d176876364825de3b5e11746a49add3125a4511003e24002f8dda270347d6
-  data.tar.gz: 468ebb8a26dadc72b3f0d9fdb0e9a2f8a39b2e94418c555926fe0b12d0ea0b8a
+  metadata.gz: 5891083b3cb25419145aab30a963c61f28973c40b8a4a74ea080b63bc970670b
+  data.tar.gz: 5febe1b938ba77edef2e6955e3b8cf8a161f40e5b5f828c6cc39f5105ed734d7
 SHA512:
-  metadata.gz: c310ffa9c64a85d3cef12f2e2fa685ae52f0bfeff975ab63a1532f88be964dc2acd577b24f4a70017efb0bc4b19c0a522a56b9660686ba33c89d970959ca1690
-  data.tar.gz: 1a2293a48671a21d6f6915162c1240fa56b719e2d40947b8e46782635c6cc6cd7d4e26ee6012f7360b098d1ab04bf82f282e090fb373d9e1e9ddb982a6672dce
+  metadata.gz: 87441e69b4caa9ac627e82c27e3d0b0e15162da1587c3bdb7ed4f5c2102fdda02f583df01652676d056b60af24fa9c67dedf38e38b1dfed346211f439de640c2
+  data.tar.gz: a725d1696dc0e7a3ee19bc3c46c1248f0ada9185bb492f44ea5c571944d98dbb6eb0f69625f68169ed931717782438524bbdc337014ea83116ad60a2d565b545

data/README.md

@@ -74,6 +74,33 @@ result = OpenapiContracts.match($doc, response, options = {})
 raise result.errors.merge("/n") unless result.valid?
 ```
 
+## Coverage reporting
+
+You can generate a coverage report, giving an indication how many of your OpenApi operations and
+responses are verified.
+
+To enable the report, set the configuration `OpenapiContracts.collect_coverage = true`.
+
+After the tests completed, you can generate the JSON file, for example:
+
+```ruby
+RSpec.configure do |c|
+  c.after(:suite) do
+    $your_api_doc.coverage.report.generate(Rails.root.join("openapi_coverage.json"))
+  end
+end
+```
+
+In case you run tests on multiple nodes and need to merge reports:
+
+```ruby
+OpenapiContracts::Coverage.merge_reports(
+  $your_api_doc,
+  *Dir[Rails.root.join("openapi_coverage_*.json")]
+).generate(Rails.root.join("openapi_coverage.json"))
+
+```
+
 ## How it works
 
 It uses the `request.path`, `request.method`, `status` and `headers` on the test subject
@@ -88,16 +115,7 @@ Then it does the following checks:
 
 ## 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. 
+None at the moment :)
 
 ## Future plans
 

data/lib/openapi_contracts/coverage/report.rb

@@ -0,0 +1,63 @@
+class OpenapiContracts::Coverage
+  class Report
+    def self.merge(doc, *reports)
+      reports.each_with_object(Report.new(doc)) do |r, m|
+        m.merge!(r)
+      end
+    end
+
+    attr_reader :data
+
+    def as_json(*)
+      report
+    end
+
+    def initialize(doc, data = {})
+      @doc = doc
+      @data = data
+    end
+
+    def generate(pathname)
+      File.write(pathname, JSON.pretty_generate(report))
+    end
+
+    def merge!(data)
+      @data.deep_merge!(data) { |_key, val1, val2| val1 + val2 }
+    end
+
+    def meta
+      {
+        'operations' => {
+          'covered' => total_covered_operations,
+          'total'   => @doc.operations.count
+        },
+        'responses'  => {
+          'covered' => total_covered_responses,
+          'total'   => @doc.responses.count
+        }
+      }.tap do |d|
+        d['operations']['quota'] = d['operations']['covered'].to_f / d['operations']['total']
+        d['responses']['quota'] = d['responses']['covered'].to_f / d['responses']['total']
+      end
+    end
+
+    private
+
+    def report
+      {
+        'meta'  => meta,
+        'paths' => @data
+      }
+    end
+
+    def total_covered_operations
+      @doc.operations.select { |o| @data.dig(o.path.to_s, o.verb).present? }.count
+    end
+
+    def total_covered_responses
+      @doc.responses.select { |r|
+        @data.dig(r.operation.path.to_s, r.operation.verb, r.status).present?
+      }.count
+    end
+  end
+end

data/lib/openapi_contracts/coverage/store.rb

@@ -0,0 +1,19 @@
+class OpenapiContracts::Coverage
+  class Store
+    attr_accessor :data
+
+    def initialize
+      @data = {}
+    end
+
+    def clear!
+      @data = {}
+    end
+
+    def increment!(path, method, status, media_type)
+      keys = [path, method, status]
+      val = @data.dig(*keys) || Hash.new(0).tap { |h| OpenapiContracts.hash_bury!(@data, keys, h) }
+      val[media_type] += 1
+    end
+  end
+end

data/lib/openapi_contracts/coverage.rb

@@ -0,0 +1,24 @@
+module OpenapiContracts
+  class Coverage
+    autoload :Report, 'openapi_contracts/coverage/report'
+    autoload :Store,  'openapi_contracts/coverage/store'
+
+    def self.merge_reports(doc, *others)
+      reports = others.map { |fp| JSON(File.read(fp))['paths'] }
+      Report.merge(doc, *reports)
+    end
+
+    attr_reader :store
+
+    def initialize(doc)
+      @store = Store.new
+      @doc = doc
+    end
+
+    delegate :clear!, :data, :increment!, to: :store
+
+    def report
+      Report.new(@doc, store.data)
+    end
+  end
+end

data/lib/openapi_contracts/doc/operation.rb

@@ -2,18 +2,24 @@ module OpenapiContracts
   class Doc::Operation
     include Doc::WithParameters
 
+    attr_reader :path
+
     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)]
+      @responses = spec.navigate('responses').each.to_h do |status, subspec|
+        [status, Doc::Response.new(self, status, subspec)]
       end
     end
 
+    def verb
+      @spec.pointer[2]
+    end
+
     def request_body
       return @request_body if instance_variable_defined?(:@request_body)
 
-      @request_body = @spec.navigate('requestBody')&.then { |s| Doc::Request.new(s) }
+      @request_body = @spec.navigate('requestBody').presence&.then { |s| Doc::Request.new(s) }
     end
 
     def responses

data/lib/openapi_contracts/doc/parameter.rb

@@ -28,10 +28,7 @@ module OpenapiContracts
     private
 
     def schemer
-      @schemer ||= begin
-        schema = @spec.navigate('schema')
-        JSONSchemer.schema(Validators::SchemaValidation.build_validation_schema(schema))
-      end
+      @schemer ||= Validators::SchemaValidation.validation_schemer(@spec.navigate('schema'))
     end
 
     def integer_parameter_matches?(value)

data/lib/openapi_contracts/doc/path.rb

@@ -10,6 +10,9 @@ module OpenapiContracts
       @path = path
       @spec = spec
       @supported_methods = HTTP_METHODS & @spec.keys
+      @operations = @supported_methods.to_h do |verb|
+        [verb, Doc::Operation.new(self, @spec.navigate(verb))]
+      end
     end
 
     def dynamic?
@@ -17,7 +20,7 @@ module OpenapiContracts
     end
 
     def operations
-      @supported_methods.each.lazy.map { |m| Doc::Operation.new(self, @spec.navigate(m)) }
+      @operations.each_value
     end
 
     def path_regexp
@@ -34,13 +37,15 @@ module OpenapiContracts
     end
 
     def supports_method?(method)
-      @supported_methods.include?(method)
+      @operations.key?(method)
     end
 
-    def with_method(method)
-      return unless supports_method?(method)
+    def to_s
+      @path
+    end
 
-      Doc::Operation.new(self, @spec.navigate(method))
+    def with_method(method)
+      @operations[method]
     end
   end
 end

data/lib/openapi_contracts/doc/pointer.rb

@@ -22,7 +22,7 @@ module OpenapiContracts
       "<#{self.class.name}#{to_a}>"
     end
 
-    delegate :empty?, to: :@segments
+    delegate :any?, :empty?, :[], to: :@segments
 
     def navigate(*segments)
       self.class[to_a + segments]

data/lib/openapi_contracts/doc/response.rb

@@ -1,6 +1,12 @@
 module OpenapiContracts
   class Doc::Response
-    def initialize(schema)
+    attr_reader :coverage, :schema, :status, :operation
+
+    delegate :pointer, to: :schema
+
+    def initialize(operation, status, schema)
+      @operation = operation
+      @status = status
       @schema = schema.follow_refs
     end
 

data/lib/openapi_contracts/doc/schema.rb

@@ -57,7 +57,8 @@ module OpenapiContracts
       pointer.to_json_schemer_pointer
     end
 
-    delegate :dig, :fetch, :keys, :key?, :[], :to_h, to: :resolve
+    delegate :dig, to: :resolve, allow_nil: true
+    delegate :fetch, :keys, :key?, :[], :to_h, to: :resolve
 
     def at_pointer(pointer)
       self.class.new(raw, pointer)
@@ -67,6 +68,10 @@ module OpenapiContracts
       @raw['openapi']&.then { |v| Gem::Version.new(v) }
     end
 
+    def presence
+      resolve.present? ? self : nil
+    end
+
     # Returns the actual sub-specification contents at the pointer of this Specification
     def resolve
       @pointer.walk(@raw)

data/lib/openapi_contracts/doc.rb

@@ -14,7 +14,7 @@ module OpenapiContracts
       new Parser.call(dir, filename)
     end
 
-    attr_reader :schema
+    attr_reader :coverage, :schema
 
     def initialize(raw)
       @schema = Schema.new(raw)
@@ -22,6 +22,7 @@ module OpenapiContracts
         [path, Path.new(path, @schema.at_pointer(Doc::Pointer['paths', path]))]
       end
       @dynamic_paths = paths.select(&:dynamic?)
+      @coverage = Coverage.new(self)
     end
 
     # Returns an Enumerator over all paths
@@ -33,14 +34,21 @@ module OpenapiContracts
       OperationRouter.new(self).route(path, method.downcase)
     end
 
+    # Returns an Enumerator over all Operations
+    def operations(&block)
+      return enum_for(:operations) unless block_given?
+
+      paths.each do |path|
+        path.operations.each(&block)
+      end
+    end
+
     # Returns an Enumerator over all Responses
     def responses(&block)
       return enum_for(:responses) unless block_given?
 
-      paths.each do |path|
-        path.operations.each do |operation|
-          operation.responses.each(&block)
-        end
+      operations.each do |operation|
+        operation.responses.each(&block)
       end
     end
 

data/lib/openapi_contracts/match.rb

@@ -19,11 +19,20 @@ module OpenapiContracts
       return @errors.empty? if instance_variable_defined?(:@errors)
 
       @errors = matchers.call
+      @doc.coverage.increment!(operation.path.to_s, request_method, status, media_type) if collect_coverage?
       @errors.empty?
     end
 
     private
 
+    def collect_coverage?
+      OpenapiContracts.collect_coverage && @request.present? && @errors.empty? && !@options[:nocov]
+    end
+
+    def media_type
+      @response.headers['Content-Type']&.split(';')&.first || 'no_content'
+    end
+
     def matchers
       env = Env.new(
         options:   @options,
@@ -39,10 +48,7 @@ module OpenapiContracts
     end
 
     def operation
-      @doc.operation_for(
-        @options.fetch(:path, @request.path),
-        @request.request_method.downcase
-      )
+      @operation ||= @doc.operation_for(path, request_method)
     end
 
     def request_compatible?
@@ -54,5 +60,17 @@ module OpenapiContracts
       ancestors = @response.class.ancestors.map(&:to_s)
       MIN_RESPONSE_ANCESTORS.all? { |s| ancestors.include?(s) }
     end
+
+    def request_method
+      @request.request_method.downcase
+    end
+
+    def path
+      @options.fetch(:path, @request.path)
+    end
+
+    def status
+      @response.status.to_s
+    end
   end
 end

data/lib/openapi_contracts/parser.rb

@@ -2,7 +2,7 @@ module OpenapiContracts
   class Parser
     autoload :Transformers, 'openapi_contracts/parser/transformers'
 
-    TRANSFORMERS = [Transformers::Nullable, Transformers::Pointer].freeze
+    TRANSFORMERS = [Transformers::Pointer].freeze
 
     def self.call(dir, filename)
       new(dir.join(filename)).parse
@@ -20,13 +20,17 @@ module OpenapiContracts
       @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.delete('$ref') # ref file pointers should be in the file list so save to delete
         target.merge! file_to_data(path, pointer)
       end
     end
 
     private
 
+    # file list consists of
+    # - root file
+    # - all files in components/
+    # - all path files referenced by the root file
     def build_file_list
       list = {@rootfile.relative_path_from(@cwd) => Doc::Pointer[]}
       Dir[File.expand_path('components/**/*.yaml', @cwd)].each do |file|

data/lib/openapi_contracts/rspec.rb

@@ -19,9 +19,11 @@ RSpec::Matchers.define :match_openapi_doc do |doc, options = {}| # rubocop:disab
     desc
   end
 
+  # :nocov:
   failure_message do |_response|
     @errors.map { |e| "* #{e}" }.join("\n")
   end
+  # :nocov:
 
   def with_http_status(status)
     if status.is_a? Symbol

data/lib/openapi_contracts/validators/schema_validation.rb

@@ -2,37 +2,31 @@ module OpenapiContracts::Validators
   module SchemaValidation
     module_function
 
-    def build_validation_schema(schema)
-      schema.raw.merge(
-        '$ref'    => schema.fragment,
-        '$schema' => schema_draft_version(schema)
-      )
+    def error_to_message(error)
+      msg = error['error']
+      msg.sub!(/^value/, error['data'].to_json) if error['data'].to_json.length < 50
+      msg
     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
+    def schema_draft_version(schema)
+      if schema.openapi_version.blank? || schema.openapi_version < Gem::Version.new('3.1')
+        JSONSchemer.openapi30
       else
-        "#{error['data'].inspect}#{pointer} does not match the schema"
+        JSONSchemer.openapi31
       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#'
+    def validation_schemer(schema)
+      schemer = JSONSchemer.schema(schema.raw, meta_schema: schema_draft_version(schema))
+      if schema.pointer.any?
+        schemer.ref(schema.fragment)
       else
-        # >= 3.1 is actually comptable with 2020-12 but not yet supported by json-schemer
-        'http://json-schema.org/draft-07/schema#'
+        schemer
       end
     end
 
     def validate_schema(schema, data)
-      schemer = JSONSchemer.schema(build_validation_schema(schema))
-      schemer.validate(data).map do |err|
+      validation_schemer(schema).validate(data).map do |err|
         error_to_message(err)
       end
     end

data/lib/openapi_contracts.rb

@@ -11,6 +11,7 @@ require 'rack'
 require 'yaml'
 
 module OpenapiContracts
+  autoload :Coverage,        'openapi_contracts/coverage'
   autoload :Doc,             'openapi_contracts/doc'
   autoload :Helper,          'openapi_contracts/helper'
   autoload :Match,           'openapi_contracts/match'
@@ -19,13 +20,28 @@ module OpenapiContracts
   autoload :PayloadParser,   'openapi_contracts/payload_parser'
   autoload :Validators,      'openapi_contracts/validators'
 
+  include ActiveSupport::Configurable
+
   Env = Struct.new(:operation, :options, :request, :response, keyword_init: true)
 
+  config_accessor(:collect_coverage) { false }
+
   module_function
 
   def match(doc, response, options = {})
     Match.new(doc, response, options)
   end
+
+  def hash_bury(hash, keys, value)
+    other = keys.reverse.reduce(value) { |m, k| {k => m} }
+    hash.deep_merge other
+  end
+
+  def hash_bury!(hash, keys, value)
+    other = keys.reverse.reduce(value) { |m, k| {k => m} }
+    hash.deep_merge! other
+    other
+  end
 end
 
 require 'openapi_contracts/rspec' if defined?(RSpec)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_contracts
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - mkon
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-03 00:00:00.000000000 Z
+date: 2023-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.3
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.3
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -92,28 +92,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.54.1
+        version: 1.56.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.54.1
+        version: 1.56.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.22.0
+        version: 2.23.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.22.0
+        version: 2.23.2
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -137,6 +137,9 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/openapi_contracts.rb
+- lib/openapi_contracts/coverage.rb
+- lib/openapi_contracts/coverage/report.rb
+- lib/openapi_contracts/coverage/store.rb
 - lib/openapi_contracts/doc.rb
 - lib/openapi_contracts/doc/header.rb
 - lib/openapi_contracts/doc/operation.rb
@@ -153,7 +156,6 @@ files:
 - 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
@@ -188,7 +190,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: Openapi schemas as API contracts

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

@@ -1,10 +0,0 @@
-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