openapi_first 3.4.2 → 4.0.0

data/lib/openapi_first/test/coverage/request_task.rb

@@ -9,10 +9,11 @@ module OpenapiFirst
       class RequestTask
         extend Forwardable
 
-        def_delegators :@request, :path, :request_method, :content_type
+        def_delegators :@request, :key, :path, :request_method, :content_type
 
-        def initialize(request_definition)
+        def initialize(request_definition, skipped: false)
           @request = request_definition
+          @skipped = skipped
           @requested = false
           @last_error_message = nil
         end
@@ -25,6 +26,10 @@ module OpenapiFirst
           @last_error_message = validated_request.error.exception_message unless validated_request.valid?
         end
 
+        def skipped?
+          @skipped == true
+        end
+
         def requested?
           @requested == true
         end

data/lib/openapi_first/test/coverage/response_task.rb

@@ -11,8 +11,9 @@ module OpenapiFirst
 
         def_delegators :@response, :status, :content_type, :key
 
-        def initialize(response_definition)
+        def initialize(response_definition, skipped: false)
           @response = response_definition
+          @skipped = skipped
           @responded = false
           @last_error_message = nil
         end
@@ -25,6 +26,10 @@ module OpenapiFirst
           @last_error_message = validated_response.error.exception_message unless validated_response.valid?
         end
 
+        def skipped?
+          @skipped == true
+        end
+
         def responded?
           @responded == true
         end

data/lib/openapi_first/test/coverage/route_task.rb

@@ -4,8 +4,30 @@ module OpenapiFirst
   module Test
     module Coverage
       RouteTask = Data.define(:path, :request_method, :requests, :responses) do
+        def skipped?
+          requests.all?(&:skipped?)
+        end
+
+        def tracked_requests
+          requests.reject(&:skipped?)
+        end
+
+        def tracked_responses
+          responses.reject(&:skipped?)
+        end
+
+        def skipped_requests
+          requests.select(&:skipped?)
+        end
+
+        def skipped_responses
+          responses.select(&:skipped?)
+        end
+
         def finished?
-          requests.all?(&:finished?) && responses.all?(&:finished?)
+          return false if skipped?
+
+          tracked_requests.all?(&:finished?) && tracked_responses.all?(&:finished?)
         end
 
         def summary

data/lib/openapi_first/test/coverage/skipped_summary.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # Shared reporting of skipped requests and responses for coverage reporters.
+      module SkippedSummary
+        def log_skipped_summary(coverage_result)
+          requests = coverage_result.skipped_requests_count
+          responses = coverage_result.skipped_responses_count
+          return if requests.zero? && responses.zero?
+
+          logger.info "API coverage skipped #{requests} request(s) and #{responses} response(s)."
+          return if requests.zero?
+
+          logger.warn "#{requests} request(s) were skipped entirely. " \
+                      'These requests are excluded from API coverage and are not contract-tested at all.'
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/coverage/terminal_reporter.rb

@@ -5,17 +5,14 @@ module OpenapiFirst
     module Coverage
       # Reports coverage to a logger using ANSI-coloured lines.
       class TerminalReporter
+        include SkippedSummary
+
         def initialize(verbose: false, focused: true, logger: Test.logger)
           @verbose = verbose
           @focused = focused && !verbose
           @logger = logger
         end
 
-        def format(coverage_result)
-          logger.warn 'DEPRECATION WARNING: TerminalReporter#format is deprecated, use #report instead.'
-          report(coverage_result)
-        end
-
         def report(coverage_result)
           coverage = coverage_result.coverage
           if coverage.zero?
@@ -23,13 +20,14 @@ module OpenapiFirst
                         'Make sure to observe your application using OpenapiFirst::Test.'
           end
           coverage_result.plans.each { |plan| format_plan(plan) } if coverage.positive?
+          log_skipped_summary(coverage_result)
         end
 
         private attr_reader :out, :verbose, :focused, :logger
 
         private
 
-        def format_plan(plan) # rubocop:disable Metrics/PerceivedComplexity
+        def format_plan(plan)
           logger.info "API validation coverage for #{plan.api_identifier}: #{plan.coverage}%"
           return if plan.done? && !verbose
 
@@ -37,9 +35,7 @@ module OpenapiFirst
           focused_route = requested_routes_count <= 1 && focused
 
           plan.routes.each do |route|
-            next if route.finished? && !verbose
-
-            next if route.requests.none?(&:requested?) && focused_route
+            next unless report_route?(route, focused_route)
 
             format_requests(route.requests)
 
@@ -47,9 +43,19 @@ module OpenapiFirst
           end
         end
 
+        def report_route?(route, focused_route)
+          return verbose if route.skipped?
+          return false if route.finished? && !verbose
+          return false if focused_route && route.requests.none?(&:requested?)
+
+          true
+        end
+
         def format_requests(requests)
           requests.each do |request|
-            if request.finished?
+            if request.skipped?
+              log_skipped "⚠ #{request_label(request)} – Skipped!" if verbose
+            elsif request.finished?
               log_success "✓ #{request_label(request)}"
             else
               log_error "❌ #{request_label(request)} – #{explain_unfinished_request(request)}"
@@ -59,7 +65,9 @@ module OpenapiFirst
 
         def format_responses(responses)
           responses.each do |response|
-            if response.finished?
+            if response.skipped?
+              log_skipped "  #{response_label(response)} – Skipped!" if verbose
+            elsif response.finished?
               log_success "  ✓  #{response_label(response)}" if verbose
             else
               log_error "  ❌ #{response_label(response)} – #{explain_unfinished_response(response)}"
@@ -98,6 +106,10 @@ module OpenapiFirst
           logger.info "\e[32m#{msg}\e[0m"
         end
 
+        def log_skipped(msg)
+          logger.info "\e[33m#{msg}\e[0m"
+        end
+
         def log_error(msg)
           logger.error "\e[31m#{msg}\e[0m"
         end

data/lib/openapi_first/test/coverage.rb

@@ -4,6 +4,7 @@ require_relative 'coverage/plan'
 require_relative 'coverage/tracker'
 require_relative 'coverage/covered_request'
 require_relative 'coverage/covered_response'
+require_relative 'coverage/skipped_summary'
 require 'drb'
 
 module OpenapiFirst
@@ -15,10 +16,15 @@ module OpenapiFirst
       autoload :TerminalReporter, 'openapi_first/test/coverage/terminal_reporter'
       autoload :HtmlReporter, 'openapi_first/test/coverage/html_reporter'
 
-      # @deprecated Use {TerminalReporter} instead.
-      TerminalFormatter = TerminalReporter
+      Result = Data.define(:plans, :coverage) do
+        def skipped_requests_count
+          plans.sum(&:skipped_requests_count)
+        end
 
-      Result = Data.define(:plans, :coverage)
+        def skipped_responses_count
+          plans.sum(&:skipped_responses_count)
+        end
+      end
 
       class << self
         def start(skip_response: nil, skip_route: nil)

data/lib/openapi_first/test.rb

@@ -5,7 +5,64 @@ require_relative 'test/configuration'
 require_relative 'registry'
 
 module OpenapiFirst
-  # Test integration
+  # Test integration for contract testing. Use this to validate requests/responses against a
+  # registered OAD while your test suite runs, and tracks which parts of the API
+  # description have been exercised.
+  #
+  # @example Basic setup (e.g. in spec_helper.rb)
+  #   require 'openapi_first'
+  #   OpenapiFirst::Test.setup
+  #
+  # {.setup} prepares coverage tracking and OAD registration. To actually validate the
+  # requests/responses that happen during your tests, you also have to observe your
+  # application, i.e. wrap it with silent request/response validation. There are three ways
+  # to do this:
+  #
+  # 1. Include {Methods}, which adds an `app` method wrapping your rack app for rack-test.
+  #    This is the easiest option if you don't already define `app` yourself:
+  #      RSpec.configure do |config|
+  #        config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+  #      end
+  # 2. Call {.observe} to inject validation directly into an app class or instance
+  #    , if you can't rely on rack-test's `app` method:
+  #      OpenapiFirst::Test.observe(Rails.application)
+  # 3. Call {.app} to wrap an app instance yourself, e.g. if you already define your own
+  #    `app` method and only want to wrap what it returns:
+  #      def app
+  #        OpenapiFirst::Test.app(MyApp.new)
+  #      end
+  #
+  # @example Configure via the block passed to .setup
+  #   OpenapiFirst::Test.setup do |test|
+  #     test.register('openapi/openapi.yaml')
+  #
+  #     # Ignore certain request/response errors instead of raising them
+  #     test.ignore_request_error do |validated_request|
+  #       validated_request.path.start_with?('/legacy') && validated_request.unknown?
+  #     end
+  #     test.ignore_response_error do |validated_response, rack_request|
+  #       validated_response.error.type == :response_status_not_found
+  #     end
+  #
+  #     # Response status codes that are okay to leave uncovered (default: 401, 404, 500)
+  #     test.ignored_unknown_status << 403
+  #     test.ignore_unknown_response_status = true # or: ignore all unknown status codes
+  #
+  #     # Don't raise when a request doesn't match the API description at all
+  #     test.ignore_unknown_requests = true
+  #
+  #     # Exclude parts of the API description from coverage tracking
+  #     test.skip_response_coverage { |response_definition| response_definition.status == '5XX' }
+  #     test.skip_coverage { |path, request_method| path == '/internal' && request_method == 'GET' }
+  #
+  #     # Require minimm of 95% coverage of the API description (default: 100)
+  #     test.minimum_coverage = 95
+  #
+  #     # Report coverage always (default), only warn, or not at all: true / :warn / false
+  #     test.report_coverage = :warn
+  #   end
+  #
+  # See {OpenapiFirst::Test::Configuration} for the full list of options.
   module Test # rubocop:disable Metrics/ModuleLength
     autoload :Coverage, 'openapi_first/test/coverage'
     autoload :Methods, 'openapi_first/test/methods'
@@ -58,7 +115,7 @@ module OpenapiFirst
               'Please register your API description via ' \
               "`OpenapiFirst.register('myopenapi.yaml)` or " \
               'in a block passed to `OpenapiFirst::Test.setup` like this: ' \
-              "`OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }` " \
+              "`OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }` "
 
       end
 
@@ -83,22 +140,23 @@ module OpenapiFirst
       return unless configuration.report_coverage == true
 
       coverage = Coverage.result.coverage
-      return if coverage >= configuration.minimum_coverage
+      minimum_coverage = configuration.minimum_coverage
 
-      puts "API Coverage fails with exit 2, because not all described requests and responses have been tested (#{coverage.round(4)}% covered)." # rubocop:disable Layout/LineLength
+      if coverage < minimum_coverage
+        logger.error "API Coverage fails with exit 2, because not all described requests and responses have been tested (#{coverage.round(4)}% covered)." # rubocop:disable Layout/LineLength
 
-      exit 2
+        exit 2
+      end
+
+      return unless coverage - minimum_coverage >= 1.0
+
+      logger.warn "API Coverage (#{coverage.round(4)}%) is higher than the configured minimum_coverage (#{minimum_coverage}%). You should probably increase minimum_coverage to #{coverage.round(4)}." # rubocop:disable Layout/LineLength
     end
 
     # Print the coverage report
     # @param reporter A reporter class to render the report.
-    # @param formatter @deprecated Alias for `reporter:`.
     # @return [IO] An output where to puts the report.
-    def self.report_coverage(reporter: Coverage::TerminalReporter, formatter: nil, **)
-      if formatter
-        warn 'DEPRECATION WARNING: Test.report_coverage(formatter:) is deprecated, use reporter: instead.'
-        reporter = formatter
-      end
+    def self.report_coverage(reporter: Coverage::TerminalReporter, **)
       reporter.new(**).report(Coverage.result)
     end
 

data/lib/openapi_first/validators/multipart_request_body.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../schema/validation_result'
+
+module OpenapiFirst
+  module Validators
+    class MultipartRequestBody
+      FILE_UPLOAD_PLACEHOLDER = String.new('', encoding: Encoding::BINARY).freeze
+
+      def initialize(content_schema:)
+        @schema = content_schema
+      end
+
+      def call(parsed_request)
+        body = parsed_request.body
+        return if body.nil?
+
+        uploads = collect_file_uploads(body)
+        uploads.each_key { write_at(body, _1, FILE_UPLOAD_PLACEHOLDER) }
+        begin
+          validate(body)
+        ensure
+          uploads.each { |path, upload| write_at(body, path, upload) }
+        end
+      end
+
+      private
+
+      def validate(body)
+        validation = Schema::ValidationResult.new(
+          @schema.validate(body, access_mode: 'write')
+        )
+        Failure.new(:invalid_body, errors: validation.errors) if validation.error?
+      end
+
+      def collect_file_uploads(value, path = [], result = {})
+        case value
+        when ::Hash
+          if value.key?(:tempfile)
+            result[path] = value unless path.empty?
+          else
+            value.each { |key, item| collect_file_uploads(item, path + [key], result) }
+          end
+        when ::Array
+          value.each_with_index { |item, index| collect_file_uploads(item, path + [index], result) }
+        end
+        result
+      end
+
+      def write_at(root, path, value)
+        *parents, key = path
+        container = parents.empty? ? root : root.dig(*parents)
+        container[key] = value if container
+      end
+    end
+  end
+end

data/lib/openapi_first/validators/request_body.rb

@@ -1,20 +1,33 @@
 # frozen_string_literal: true
 
+require_relative 'multipart_request_body'
+
 module OpenapiFirst
   module Validators
     class RequestBody
-      def initialize(content_schema:, required_request_body:)
+      MULTIPART = %r{\Amultipart/}i
+      private_constant :MULTIPART
+
+      REQUIREMENT = lambda do |parsed_request|
+        Failure.new(:invalid_body, message: 'Request body must not be empty') if parsed_request.body.nil?
+      end
+      private_constant :REQUIREMENT
+
+      def self.for(content_schema:, required_request_body:, content_type:)
+        validators = []
+        validators << REQUIREMENT if required_request_body
+        klass = MULTIPART.match?(content_type.to_s) ? MultipartRequestBody : self
+        validators << klass.new(content_schema:)
+        validators
+      end
+
+      def initialize(content_schema:)
         @schema = content_schema
-        @required = required_request_body
       end
 
       def call(parsed_request)
         body = parsed_request.body
-        if body.nil?
-          return Failure.new(:invalid_body, message: 'Request body must not be empty') if @required
-
-          return
-        end
+        return if body.nil?
 
         validation = Schema::ValidationResult.new(
           @schema.validate(body, access_mode: 'write')

data/lib/openapi_first/validators/request_parameters.rb

@@ -2,8 +2,9 @@
 
 module OpenapiFirst
   module Validators
+    # @visibility private
     module RequestParameters
-      RequestHeaders = Data.define(:schema) do
+      Headers = Data.define(:schema) do
         def call(parsed_request)
           validation = schema.validate(parsed_request.headers)
           Failure.new(:invalid_header, errors: validation.errors) if validation.error?
@@ -24,7 +25,7 @@ module OpenapiFirst
         end
       end
 
-      RequestCookies = Data.define(:schema) do
+      Cookies = Data.define(:schema) do
         def call(parsed_request)
           validation = schema.validate(parsed_request.cookies)
           Failure.new(:invalid_cookie, errors: validation.errors) if validation.error?
@@ -34,8 +35,8 @@ module OpenapiFirst
       VALIDATORS = {
         path_schema: Path,
         query_schema: Query,
-        header_schema: RequestHeaders,
-        cookie_schema: RequestCookies
+        header_schema: Headers,
+        cookie_schema: Cookies
       }.freeze
 
       def self.for(args)

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '3.4.2'
+  VERSION = '4.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 3.4.2
+  version: 4.0.0
 platform: ruby
 authors:
 - Andreas Haller
@@ -57,26 +57,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: openapi_parameters
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.12.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.12.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -117,20 +97,29 @@ files:
 - lib/openapi_first/errors.rb
 - lib/openapi_first/failure.rb
 - lib/openapi_first/file_loader.rb
-- lib/openapi_first/header.rb
 - lib/openapi_first/json.rb
 - lib/openapi_first/middlewares/request_validation.rb
 - lib/openapi_first/middlewares/response_validation.rb
+- lib/openapi_first/parameter.rb
+- lib/openapi_first/parameter/converter.rb
+- lib/openapi_first/parameter/converter/array_converter.rb
+- lib/openapi_first/parameter/converter/object_converter.rb
+- lib/openapi_first/parameter/unpackers.rb
+- lib/openapi_first/parameter_content_parsers.rb
+- lib/openapi_first/parameters_parser.rb
 - lib/openapi_first/parsed_request.rb
 - lib/openapi_first/plugins.rb
 - lib/openapi_first/plugins/x_public.rb
+- lib/openapi_first/query_string_parser.rb
 - lib/openapi_first/ref_resolver.rb
 - lib/openapi_first/registry.rb
 - lib/openapi_first/request.rb
 - lib/openapi_first/request_body_parsers.rb
+- lib/openapi_first/request_headers.rb
 - lib/openapi_first/request_validator.rb
 - lib/openapi_first/response.rb
 - lib/openapi_first/response_body_parsers.rb
+- lib/openapi_first/response_header.rb
 - lib/openapi_first/response_parser.rb
 - lib/openapi_first/response_validator.rb
 - lib/openapi_first/router.rb
@@ -140,6 +129,7 @@ files:
 - lib/openapi_first/schema/hash.rb
 - lib/openapi_first/schema/validation_error.rb
 - lib/openapi_first/schema/validation_result.rb
+- lib/openapi_first/sinatra.rb
 - lib/openapi_first/test.rb
 - lib/openapi_first/test/app.rb
 - lib/openapi_first/test/callable.rb
@@ -155,6 +145,7 @@ files:
 - lib/openapi_first/test/coverage/request_task.rb
 - lib/openapi_first/test/coverage/response_task.rb
 - lib/openapi_first/test/coverage/route_task.rb
+- lib/openapi_first/test/coverage/skipped_summary.rb
 - lib/openapi_first/test/coverage/terminal_reporter.rb
 - lib/openapi_first/test/coverage/tracker.rb
 - lib/openapi_first/test/logger.rb
@@ -165,6 +156,7 @@ files:
 - lib/openapi_first/test/plain_helpers.rb
 - lib/openapi_first/validated_request.rb
 - lib/openapi_first/validated_response.rb
+- lib/openapi_first/validators/multipart_request_body.rb
 - lib/openapi_first/validators/request_body.rb
 - lib/openapi_first/validators/request_parameters.rb
 - lib/openapi_first/validators/response_body.rb
@@ -193,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: OpenAPI based request validation, response validation, contract-testing and
   coverage

data/lib/openapi_first/header.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module OpenapiFirst
-  Header = Data.define(:name, :required?, :schema, :node) do
-    def resolved_schema
-      node['schema']&.resolved
-    end
-  end
-end