openapi_first 3.4.3 → 4.0.0

data/lib/openapi_first/request.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'openapi_parameters'
+require_relative 'request_headers'
 require_relative 'parsed_request'
 require_relative 'request_validator'
 require_relative 'validated_request'
@@ -21,23 +21,24 @@ module OpenapiFirst
       @operation = operation_object
       @allow_empty_content = content_type.nil? || required_body == false
       @key = key
-      @query_parser = parameters.query&.then { |params| OpenapiParameters::Query.new(params) }
-      @path_parser = parameters.path&.then { |params| OpenapiParameters::Path.new(params) }
-      @headers_parser = parameters.header&.then { |params| OpenapiParameters::Header.new(params) }
-      @cookies_parser = parameters.cookie&.then { |params| OpenapiParameters::Cookie.new(params) }
+      @parameters = parameters.all
+      @query_parser = parameters.query_parser
+      @path_parser = parameters.path_parser
+      @header_parser = parameters.header_parser
+      @cookie_parser = parameters.cookie_parser
       @body_parsers = build_body_parser(content_type, encoding) if content_type
       @validator = RequestValidator.new(
         content_schema:,
+        content_type:,
         required_request_body: required_body == true,
         path_schema: parameters.path_schema,
         query_schema: parameters.query_schema,
         header_schema: parameters.header_schema,
         cookie_schema: parameters.cookie_schema
       )
-      @parameters = parameters
     end
 
-    attr_reader :content_type, :content_schema, :operation, :request_method, :path, :key, :query_schema, :parameters
+    attr_reader :content_type, :content_schema, :operation, :request_method, :path, :key, :parameters
     private attr_reader :query_parser
 
     def allow_empty_content?
@@ -66,15 +67,15 @@ module OpenapiFirst
       [ParsedRequest.new(
         path: @path_parser&.unpack(route_params),
         query:,
-        headers: @headers_parser&.unpack_env(request.env),
-        cookies: @cookies_parser&.unpack(request.env[Rack::HTTP_COOKIE]),
+        headers: @header_parser&.unpack(RequestHeaders.new(request.env)),
+        cookies: @cookie_parser&.unpack(Rack::Utils.parse_cookies_header(request.env[Rack::HTTP_COOKIE])),
         body:
       ), nil]
     end
 
     def parse_query(query_string)
       [@query_parser&.unpack(query_string), nil]
-    rescue OpenapiParameters::InvalidParameterError
+    rescue Rack::Utils::InvalidParameterError
       [nil, Failure.new(:invalid_query, message: 'Invalid query parameter.')]
     end
 

data/lib/openapi_first/request_body_parsers.rb

@@ -39,10 +39,6 @@ module OpenapiFirst
       Failure.new(:invalid_body, message: 'Failed to parse request body as JSON')
     end)
 
-    # Parses multipart/form-data requests and currently puts the contents of a file upload at the parsed hash values.
-    # NOTE: This behavior will probably change in the next major version.
-    #       The uploaded file should not be read during request validation.
-    #
     # Honors the OpenAPI `encoding` map: when a top-level field has
     # `contentType: application/json` (or any */json), the field's raw value
     # is JSON-parsed before schema validation.
@@ -65,9 +61,11 @@ module OpenapiFirst
       private
 
       def decode_field(name, value)
-        raw = unpack_value(value)
         content_type = @encoding.dig(name, 'contentType')
-        return raw unless content_type && raw.is_a?(String) && json?(content_type)
+        return unpack_value(value) unless content_type && json?(content_type)
+
+        raw = read_raw(value)
+        return unpack_value(value) if raw.nil?
 
         JSON.parse(raw)
       rescue JSON::ParserError => e
@@ -79,10 +77,16 @@ module OpenapiFirst
         content_type.match?(%r{[/+]json\b}i)
       end
 
+      def read_raw(value)
+        return value if value.is_a?(String)
+
+        value[:tempfile]&.read if value.is_a?(Hash) && value.key?(:tempfile)
+      end
+
       def unpack_value(value)
         return value.map { unpack_value(_1) } if value.is_a?(Array)
         return value unless value.is_a?(Hash)
-        return value[:tempfile]&.read if value.key?(:tempfile)
+        return value if value.key?(:tempfile)
 
         value.transform_values { unpack_value(_1) }
       end

data/lib/openapi_first/request_headers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # A wrapper around the Rack env hash that allows accessing headers by header name
+  # @visibility private
+  class RequestHeaders
+    # This was copied from this Rack::Request PR: https://github.com/rack/rack/pull/1881
+    def initialize(env)
+      @env = env
+    end
+
+    def [](key)
+      @env[header_to_env_key(key)]
+    end
+
+    def key?(key)
+      @env.key?(header_to_env_key(key))
+    end
+
+    def header_to_env_key(key)
+      key = key.upcase
+      key.tr!('-', '_')
+      key = "HTTP_#{key}" unless %w[CONTENT_LENGTH CONTENT_TYPE].include?(key)
+      key
+    end
+  end
+end

data/lib/openapi_first/request_validator.rb

@@ -9,6 +9,7 @@ module OpenapiFirst
   class RequestValidator
     def initialize(
       content_schema:,
+      content_type:,
       required_request_body:,
       path_schema:,
       query_schema:,
@@ -16,7 +17,9 @@ module OpenapiFirst
       cookie_schema:
     )
       @validators = []
-      @validators << Validators::RequestBody.new(content_schema:, required_request_body:) if content_schema
+      if content_schema
+        @validators.concat Validators::RequestBody.for(content_schema:, required_request_body:, content_type:)
+      end
       @validators.concat Validators::RequestParameters.for(
         path_schema:,
         query_schema:,

data/lib/openapi_first/response_header.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'parameter'
+
+module OpenapiFirst
+  # A header of a response definition.
+  # @attr_reader [Parameter] parameter The header as a Parameter, which knows how to unpack a raw value.
+  ResponseHeader = Data.define(:name, :required?, :schema, :parameter)
+end

data/lib/openapi_first/response_parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'parameters_parser'
 require_relative 'response_body_parsers'
 
 module OpenapiFirst
@@ -18,7 +19,7 @@ module OpenapiFirst
 
       [ParsedResponse.new(
         body:,
-        headers: @headers_parser&.call(rack_response.headers) || {}
+        headers: @headers_parser&.unpack(rack_response.headers) || {}
       ), nil]
     end
 
@@ -39,15 +40,7 @@ module OpenapiFirst
     def build_headers_parser(headers)
       return unless headers&.any?
 
-      headers_as_parameters = headers.map do |header|
-        {
-          'name' => header.name,
-          'explode' => false,
-          'in' => 'header',
-          'schema' => header.resolved_schema
-        }
-      end
-      OpenapiParameters::Header.new(headers_as_parameters).method(:unpack)
+      ParametersParser.new(headers.map(&:parameter))
     end
   end
 end

data/lib/openapi_first/router.rb

@@ -18,6 +18,10 @@ module OpenapiFirst
     # Returned by {#routes} to introspect all routes
     Route = Data.define(:path, :request_method, :requests, :responses)
 
+    # Holds the requests/responses defined for one path + request method
+    RouteEntry = Data.define(:requests, :responses)
+    private_constant :RouteEntry
+
     NOT_FOUND = RequestMatch.new(request_definition: nil, params: nil, responses: nil, error: Failure.new(:not_found))
     private_constant :NOT_FOUND
 
@@ -32,8 +36,8 @@ module OpenapiFirst
         request_methods.filter_map do |request_method, content|
           next if request_method == :template
 
-          Route.new(path:, request_method:, requests: content[:requests].each_value.lazy.uniq,
-                    responses: content[:responses].each_value.lazy.flat_map(&:values))
+          Route.new(path:, request_method:, requests: content.requests.each_value.lazy.uniq,
+                    responses: content.responses.each_value.lazy.flat_map(&:values))
         end
       end
     end
@@ -41,14 +45,14 @@ module OpenapiFirst
     # Add a request definition
     def add_request(request, request_method:, path:, content_type: nil, allow_empty_content: false)
       route = route_at(path, request_method)
-      requests = route[:requests]
+      requests = route.requests
       requests[content_type] = request
       requests[nil] = request if allow_empty_content
     end
 
     # Add a response definition
     def add_response(response, request_method:, path:, status:, response_content_type: nil)
-      (route_at(path, request_method)[:responses][status] ||= {})[response_content_type] = response
+      (route_at(path, request_method).responses[status] ||= {})[response_content_type] = response
     end
 
     # Return all request objects that match the given path and request method
@@ -59,7 +63,23 @@ module OpenapiFirst
         return NOT_FOUND.with(error: Failure.new(:not_found, message:))
       end
 
-      contents = path_item.dig(request_method, :requests)
+      match_path_item(path_item, params, request_method, content_type:)
+    end
+
+    def match_route(request_method, template, params:, content_type: nil)
+      path_item = @static[template] || @dynamic[template]
+      unless path_item
+        message = "Request path #{template} is not defined in API description."
+        return NOT_FOUND.with(error: Failure.new(:not_found, message:))
+      end
+
+      match_path_item(path_item, params, request_method, content_type:)
+    end
+
+    private
+
+    def match_path_item(path_item, params, request_method, content_type:)
+      contents = path_item[request_method]&.requests
       return NOT_FOUND.with(error: Failure.new(:method_not_allowed)) unless contents
 
       request_definition = FindContent.call(contents, content_type)
@@ -68,12 +88,10 @@ module OpenapiFirst
         return NOT_FOUND.with(error: Failure.new(:unsupported_media_type, message:))
       end
 
-      responses = path_item.dig(request_method, :responses)
+      responses = path_item[request_method]&.responses
       RequestMatch.new(request_definition:, params:, error: nil, responses:)
     end
 
-    private
-
     def route_at(path, request_method)
       request_method = request_method.upcase
       path_item = if PathTemplate.template?(path)
@@ -81,10 +99,7 @@ module OpenapiFirst
                   else
                     @static[path] ||= {}
                   end
-      path_item[request_method] ||= {
-        requests: {},
-        responses: {}
-      }
+      path_item[request_method] ||= RouteEntry.new(requests: {}, responses: {})
     end
 
     def content_type_err(content_type)

data/lib/openapi_first/schema/hash.rb

@@ -10,7 +10,6 @@ module OpenapiFirst
       # @param required Array of required keys
       def initialize(schemas, required: nil, **options)
         @schemas = schemas
-        @options = options
         @after_property_validation = options.delete(:after_property_validation)
         schema = { 'type' => 'object' }
         schema['required'] = required if required

data/lib/openapi_first/sinatra.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+# :nocov:
+begin
+  require 'sinatra/base'
+rescue LoadError
+  raise LoadError, 'openapi_first/sinatra needs the `sinatra` gem. Add `gem "sinatra"` to your Gemfile.'
+end
+# :nocov:
+
+require 'did_you_mean'
+require 'openapi_first'
+
+module OpenapiFirst
+  # Sinatra extension to define routes by referencing operations in an OpenAPI description via operationId.
+  #
+  #   require 'openapi_first/sinatra'
+  #
+  # In a classic (top-level) app the extension is registered automatically, so the +openapi+
+  # and +operation+ keywords are available right away:
+  #
+  #   require 'sinatra'
+  #   require 'openapi_first/sinatra'
+  #
+  #   openapi 'openapi.yaml'
+  #   operation :create_customer do
+  #     json create_customer(parsed_params)
+  #   end
+  #
+  # In a modular app register it explicitly, like any other Sinatra extension:
+  #
+  #   require 'sinatra/base'
+  #   require 'openapi_first/sinatra'
+  #
+  #   class PetsApi < Sinatra::Base
+  #     register OpenapiFirst::Sinatra
+  #     openapi 'openapi.yaml'
+  #
+  #     operation :index_pets do |params|
+  #       json index_pets(params[:filter])
+  #     end
+  #
+  #     operation :create_pet do
+  #       json create_pet(parsed_body[:data])
+  #     end
+  #   end
+  #
+  # Each +operation+ route validates its request against the OpenAPI description before the block
+  # runs, so contract violations return 400/415 and the block is not reached. Validation reuses
+  # Sinatra's own routing (the operation's path template is known when the route is defined), so
+  # openapi_first does not run its own router - there is no request-validation middleware.
+  #
+  # Because routing is left to Sinatra, requests to paths without an +operation+ block fall through
+  # to Sinatra's normal handling (a 404 by default), and you can add plain Sinatra routes
+  # (health checks, assets, ...) alongside +operation+ blocks.
+  # This relaxes the strict approach of openapi_first's request validation middleware
+  # where all unknown routes that are not described in the OAD return 404. Take care to avoid API drift
+  #
+  # NOTE: Requests are matched by Sinatra's router (Mustermann), but validated against the OpenAPI path
+  # template the route was defined from, using the path parameters Sinatra extracted. The two
+  # matchers can diverge at the edges (trailing slashes, dots inside a path segment,
+  # encoded characters, ...) - a request Sinatra matches is not re-checked against openapi_first's own
+  # path matching. Avoid path shapes where the two routers disagree.
+  module Sinatra
+    PATH_PARAMETER = /\{[^}]+\}/
+    private_constant :PATH_PARAMETER
+
+    # The configuration lives in Sinatra settings (rather than plain instance variables) so a
+    # subclass of a configured app inherits the loaded description and its operation index.
+    def self.registered(app)
+      app.helpers(Helpers)
+      # Declared up front so the reader methods exist (returning nil) before #openapi runs,
+      # which keeps the "call `openapi` first" guard in #operation working.
+      app.set :openapi_definition, nil
+      app.set :openapi_operations_index, nil
+      app.set :openapi_error_response, nil
+    end
+
+    # Loads an OpenAPI description for this app. Call this once per app; the loaded description is
+    # then available via {#openapi_definition}. Each {#operation} route validates its request
+    # against the description before the block runs.
+    # @param spec [String, Symbol, OpenapiFirst::Definition] A file path, a key registered via
+    #   OpenapiFirst.register, or a Definition instance.
+    # @return [OpenapiFirst::Definition]
+    # @raise [OpenapiFirst::Error] if {#openapi} has already been called for this app.
+    def openapi(spec)
+      raise OpenapiFirst::Error, '`openapi` can only be called once per app.' if openapi_definition
+
+      definition = OpenapiFirst.load(spec)
+      set :openapi_definition, definition
+      set :openapi_operations_index, build_operation_index(definition)
+      set :openapi_error_response, OpenapiFirst.configuration.request_validation_error_response
+      definition
+    end
+
+    # Defines a route for the operation with the given +operationId+. The HTTP method and path
+    # are taken from the OpenAPI description; the block is the Sinatra route handler.
+    #
+    # If the block declares an argument, it receives {Helpers#parsed_params}:
+    #
+    #   operation(:show_pet) { |params| json find_pet(params[:id]) }
+    #
+    # A block without arguments runs as a normal Sinatra route (use {Helpers#parsed_params} inside).
+    # A block that takes a splat or optional argument (arity < 0) is also passed {Helpers#parsed_params}.
+    #
+    # Symbols are the idiomatic form (+operation :create_customer+). Use a String for operationIds
+    # that are not valid Ruby symbols, e.g. +operation 'pets.list'+.
+    # @param operation_id [String, Symbol] An operationId present in the API description.
+    # @raise [OpenapiFirst::Error] if {#openapi} has not been called yet.
+    # @raise [ArgumentError] if the operationId is not defined in the API description.
+    def operation(operation_id, &block)
+      unless openapi_operations_index
+        raise OpenapiFirst::Error, 'Call `openapi` with your API description before defining operations.'
+      end
+
+      request_method, path = openapi_operations_index.fetch(operation_id.to_s) do
+        raise ArgumentError, unknown_operation_message(operation_id.to_s)
+      end
+      public_send(request_method.downcase, sinatra_pattern(path), &operation_handler(path, block))
+    end
+
+    private
+
+    def unknown_operation_message(operation_id)
+      defined_ids = openapi_operations_index.keys
+      message = "Operation #{operation_id.inspect} is not defined in #{openapi_definition.key}."
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: defined_ids).correct(operation_id)
+      message << if suggestions.any?
+                   " Did you mean #{suggestions.map(&:inspect).join(' or ')}?"
+                 else
+                   " Defined operationIds are: #{defined_ids.join(', ')}."
+                 end
+    end
+
+    def operation_handler(path_template, block)
+      param_names = path_template.scan(PATH_PARAMETER).map! { |placeholder| placeholder[1..-2] }
+      proc do |*captures|
+        path_params = param_names.zip(captures).to_h
+        validated = settings.openapi_definition.validate_request(request, path_template:, path_params:)
+        env[OpenapiFirst::REQUEST] = validated
+        if (failure = validated.error) && (error_response = settings.openapi_error_response)
+          halt(*error_response.new(failure:).render)
+        end
+
+        block.arity.zero? ? instance_exec(&block) : instance_exec(parsed_params, &block)
+      end
+    end
+
+    def sinatra_pattern(path)
+      path.gsub(PATH_PARAMETER) { |placeholder| ":#{placeholder[1..-2].gsub(/[^A-Za-z0-9_]/, '_')}" }
+    end
+
+    def build_operation_index(definition)
+      definition.routes.each_with_object({}) do |route, index|
+        route.requests.each do |request|
+          operation_id = request.operation_id
+          next unless operation_id
+
+          entry = [route.request_method, route.path]
+          existing = index[operation_id]
+          if existing && existing != entry
+            raise OpenapiFirst::Error,
+                  "operationId #{operation_id.inspect} is used for #{existing.join(' ')} and " \
+                  "#{entry.join(' ')} in #{definition.key}. operationIds must be unique."
+          end
+
+          index[operation_id] = entry
+        end
+      end
+    end
+
+    # Helpers available inside route blocks.
+    module Helpers
+      # The merged path and query parameters parsed and coerced per the OpenAPI description. See also
+      # OpenapiFirst::ValidatedRequest#parsed_query, OpenapiFirst::ValidatedRequest#parsed_path_parameters).
+      #
+      # Sinatra's own +params+ is left untouched and still returns the raw, unparsed values. For
+      # parts that can have colliding names, read them explicitly via {#openapi_request}
+      # (e.g. +openapi_request.parsed_headers+).
+      #
+      # @return [Sinatra::IndifferentHash]
+      def parsed_params
+        ::Sinatra::IndifferentHash[openapi_request.parsed_query.merge(openapi_request.parsed_path_parameters)]
+      end
+
+      # The parsed request body
+      # @return [Sinatra::IndifferentHash, Object, nil]
+      def parsed_body
+        body = openapi_request.parsed_body
+        body.is_a?(Hash) ? ::Sinatra::IndifferentHash[body] : body
+      end
+
+      # Generates a URL for the operation with the given +operationId+, filling in any path
+      # parameters from +path_params+. Delegates to Sinatra's own +url+ helper so reverse-proxy
+      # and script-name handling is preserved.
+      #
+      #   href = operation_url(:show_pet, petId: pet.id)   # => "http://example.com/pets/42"
+      #
+      # @param operation_id [String, Symbol] An operationId present in the API description.
+      # @param path_params [Hash] Path-parameter values keyed by name (String or Symbol).
+      # @return [String] Absolute URL for the operation.
+      # @raise [ArgumentError] if the operationId is unknown or a required path parameter is missing.
+      def operation_url(operation_id, path_params = {})
+        url(settings.openapi_definition.path_for(path_params, operation_id:))
+      end
+
+      # @return [OpenapiFirst::ValidatedRequest] The validated request for the current request.
+      def openapi_request
+        env[OpenapiFirst::REQUEST]
+      end
+    end
+  end
+end
+
+# Make the +openapi+/+operation+ keywords available to classic (top-level) apps, so that
+# requiring this single file is enough. Modular apps still `register OpenapiFirst::Sinatra`.
+Sinatra.register(OpenapiFirst::Sinatra)

data/lib/openapi_first/test/configuration.rb

@@ -38,30 +38,6 @@ module OpenapiFirst
                     :ignore_unknown_requests, :ignore_unknown_response_status, :minimum_coverage, :logger
       attr_reader :report_coverage, :ignored_unknown_status
 
-      # @deprecated Use {#coverage_reporter} instead.
-      def coverage_formatter
-        warn_coverage_formatter_deprecation
-        coverage_reporter
-      end
-
-      # @deprecated Use {#coverage_reporter=} instead.
-      def coverage_formatter=(value)
-        warn_coverage_formatter_deprecation
-        self.coverage_reporter = value
-      end
-
-      # @deprecated Use {#coverage_reporter_options} instead.
-      def coverage_formatter_options
-        warn_coverage_formatter_deprecation
-        coverage_reporter_options
-      end
-
-      # @deprecated Use {#coverage_reporter_options=} instead.
-      def coverage_formatter_options=(value)
-        warn_coverage_formatter_deprecation
-        self.coverage_reporter_options = value
-      end
-
       # Set ignored unknown status codes.
       # @param [Array<Integer>] status Status codes that are okay not to cover in an OAD
       def ignored_unknown_status=(status)
@@ -130,16 +106,6 @@ module OpenapiFirst
 
         true
       end
-
-      private
-
-      def warn_coverage_formatter_deprecation
-        return if @coverage_formatter_warned
-
-        warn 'DEPRECATION WARNING: Test::Configuration#coverage_formatter(_options) is deprecated, ' \
-             'use #coverage_reporter(_options) instead.'
-        @coverage_formatter_warned = true
-      end
     end
   end
 end

data/lib/openapi_first/test/coverage/html_reporter/context.rb

@@ -12,12 +12,16 @@ module OpenapiFirst
             'API Coverage did not detect any API requests for the registered ' \
             'API descriptions. Make sure to observe your application using OpenapiFirst::Test.'
 
-          attr_reader :coverage, :plans, :verbose
+          attr_reader :coverage, :plans, :verbose, :generated_at,
+                      :skipped_requests_count, :skipped_responses_count
 
-          def initialize(coverage_result, verbose)
+          def initialize(coverage_result, verbose, generated_at: Time.now)
             @coverage = coverage_result.coverage
             @plans = coverage_result.plans
+            @skipped_requests_count = coverage_result.skipped_requests_count
+            @skipped_responses_count = coverage_result.skipped_responses_count
             @verbose = verbose
+            @generated_at = generated_at.strftime('%Y-%m-%d %H:%M:%S %z')
           end
 
           # Helper for ERB rendering only — exposes this context's binding so the
@@ -26,14 +30,12 @@ module OpenapiFirst
             binding
           end
 
-          def expand_plan?(plan)
-            verbose || plan.done?
+          def any_skipped?
+            skipped_requests_count.positive? || skipped_responses_count.positive?
           end
 
           def visible_routes(plan)
-            return plan.routes if expand_plan?(plan)
-
-            plan.routes.reject(&:finished?)
+            plan.routes
           end
 
           def any_request_made?(route)
@@ -41,27 +43,32 @@ module OpenapiFirst
           end
 
           def route_status(route)
-            return :request_problem if route.requests.none?(&:finished?)
-            return :responses_problem if any_request_made?(route) && route.responses.any? { |r| !r.finished? }
+            return :skipped if route.skipped?
+            return :request_problem if route.tracked_requests.none?(&:finished?)
+            return :responses_problem if any_request_made?(route) && route.tracked_responses.any? { |r| !r.finished? }
 
             :ok
           end
 
+          def route_class(route)
+            return 'is-skipped' if route.skipped?
+
+            route.finished? ? 'is-covered' : 'is-uncovered'
+          end
+
           def uncovered_responses_count(route)
-            route.responses.count { |r| !r.finished? }
+            route.tracked_responses.count { |r| !r.finished? }
           end
 
-          def request_items(route, plan_verbose:)
+          def request_items(route)
+            return route.requests if route.skipped?
             return [] unless any_request_made?(route) && route.requests.any?(&:content_type)
 
-            plan_verbose ? route.requests : route.requests.reject(&:finished?)
+            route.requests
           end
 
-          def response_items(route, plan_verbose:)
-            return [] unless plan_verbose || any_request_made?(route)
-            return route.responses if plan_verbose || route.responses.any? { |r| !r.finished? }
-
-            []
+          def response_items(route)
+            route.responses
           end
 
           def h(text)