openapi_first 3.4.2 → 4.0.0

data/lib/openapi_first/ref_resolver.rb

@@ -84,7 +84,7 @@ module OpenapiFirst
       def resolve_ref(pointer)
         if pointer.start_with?('#')
           value = Hana::Pointer.new(pointer[1..]).eval(context)
-          raise "Unknown reference #{pointer} in #{context}" unless value
+          raise "Unknown reference #{pointer.inspect} in #{filepath || context}" unless value
 
           return ref_resolver.for(value, filepath:, context:)
         end
@@ -93,12 +93,19 @@ module OpenapiFirst
         full_path = File.expand_path(relative_path, dir)
         return ref_resolver.load(full_path) unless file_pointer
 
-        ref_resolver.file_at(full_path, file_pointer)
+        resolved = ref_resolver.file_at(full_path, file_pointer)
+        raise "Unknown reference #{pointer.inspect} in #{filepath || context}" unless resolved
+
+        resolved
       rescue OpenapiFirst::FileNotFoundError => e
         message = "Problem with reference resolving #{pointer.inspect} in " \
                   "file #{File.absolute_path(filepath).inspect}: #{e.message}"
         raise OpenapiFirst::FileNotFoundError, message
       end
+
+      private
+
+      def mark(visited) = (visited || []) + [value.object_id]
     end
 
     # @visibility private
@@ -106,6 +113,8 @@ module OpenapiFirst
       include Resolvable
 
       def resolved = value
+
+      def dereferenced(_visited = nil) = value
     end
 
     # @visibility private
@@ -124,6 +133,19 @@ module OpenapiFirst
         value
       end
 
+      # Returns a plain Hash with all nested $refs resolved.
+      # A node that is reached again on its own path, as in a recursive schema,
+      # is returned unresolved to stop the recursion.
+      # @param visited [Array<Integer>, nil] Object ids of the nodes on the current path.
+      def dereferenced(visited = nil)
+        return value if visited&.include?(value.object_id)
+
+        visited = mark(visited)
+        return resolve_ref(value['$ref'])&.dereferenced(visited) if value.key?('$ref')
+
+        value.each_key.to_h { |key| [key, self[key]&.dereferenced(visited)] }
+      end
+
       def [](key)
         return resolve_ref(@value['$ref'])[key] if !@value.key?(key) && @value.key?('$ref')
 
@@ -154,6 +176,14 @@ module OpenapiFirst
     class Schema
       extend Forwardable
 
+      # The root context is a document, not a schema. Parsing it with only the core vocabulary
+      # keeps document keys that collide with dialect keywords (like "id" in OpenAPI 3.0)
+      # from being parsed as such and keeps them navigable for $ref pointers.
+      DOCUMENT_META_SCHEMA = JSONSchemer::Schema.new(
+        {},
+        vocabulary: { 'https://json-schema.org/draft/2020-12/vocab/core' => true }
+      )
+
       def initialize(value:, context:, base_uri:, options:)
         @value = value
         @context = context
@@ -167,10 +197,24 @@ module OpenapiFirst
 
       def schema
         @schema ||= begin
-          root_schema = JSONSchemer::Schema.new(context, base_uri:, **options)
+          root_schema = JSONSchemer::Schema.new(context, base_uri:, **options, meta_schema: DOCUMENT_META_SCHEMA)
+          apply_dialect(root_schema)
           JSONSchemer::Schema.new(value, nil, root_schema, base_uri:, **options)
         end
       end
+
+      private
+
+      # Set the dialect meta schema on the root like JSONSchemer::Schema#parse would,
+      # so that schemas resolved via $ref pointers into the document inherit it.
+      def apply_dialect(root_schema)
+        dialect = options[:meta_schema] || options.fetch(:configuration, JSONSchemer.configuration).meta_schema
+        if dialect.is_a?(String)
+          JSONSchemer::Schema::SCHEMA_KEYWORD_CLASS.new(dialect, root_schema, '$schema')
+        else
+          root_schema.meta_schema = dialect
+        end
+      end
     end
 
     # @visibility private
@@ -201,6 +245,15 @@ module OpenapiFirst
           end
         end
       end
+
+      # Returns a plain Array with all nested $refs resolved.
+      # @param visited [Array<Integer>, nil] Object ids of the nodes on the current path.
+      def dereferenced(visited = nil)
+        return value if visited&.include?(value.object_id)
+
+        visited = mark(visited)
+        value.each_index.map { self[_1]&.dereferenced(visited) }
+      end
     end
   end
 end

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?
@@ -54,9 +55,6 @@ module OpenapiFirst
       @operation['operationId']
     end
 
-    MULTIPART_CONTENT_TYPE = %r{\Amultipart/form-data\b}i
-    private_constant :MULTIPART_CONTENT_TYPE
-
     private
 
     def parse_request(request, route_params:)
@@ -69,24 +67,20 @@ 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
 
     def build_body_parser(content_type, encoding)
-      if content_type.match?(MULTIPART_CONTENT_TYPE)
-        RequestBodyParsers::MultipartBodyParser.new(encoding: encoding || {})
-      else
-        RequestBodyParsers[content_type]
-      end
+      RequestBodyParsers[content_type, { encoding: encoding || {} }]
     end
   end
 end

data/lib/openapi_first/request_body_parsers.rb

@@ -14,9 +14,12 @@ module OpenapiFirst
         parsers[pattern] = parser
       end
 
-      def [](content_type)
+      def [](content_type, options = {})
         key = parsers.keys.find { content_type.match?(_1) }
-        parsers.fetch(key) { DEFAULT }
+        parser = parsers.fetch(key) { DEFAULT }
+        return parser.new(options) if parser.is_a?(Class)
+
+        parser
       end
     end
 
@@ -36,20 +39,12 @@ 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.
     class MultipartBodyParser
-      def initialize(encoding: {})
-        @encoding = encoding || {}
-      end
-
-      def self.call(request)
-        new.call(request)
+      def initialize(options)
+        @encoding = options[:encoding] || {}
       end
 
       def call(request)
@@ -66,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
@@ -80,16 +77,22 @@ 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
     end
 
-    register('multipart/form-data', MultipartBodyParser)
+    register(%r{\Amultipart/form-data\b}i, MultipartBodyParser)
 
     register('application/x-www-form-urlencoded', lambda(&:POST))
   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)