grape 4.0.0 → 4.1.0

data/lib/grape/middleware/formatter.rb

@@ -13,12 +13,60 @@ module Grape
 
       ALL_MEDIA_TYPES = '*/*'
 
+      # The query param that names the format. See #format_from_query.
+      FORMAT_PARAM = 'format'
+
+      # @api private
+      # The format an Accept header asks for out of +mime_types+, or nil.
+      # Callers scrub the header first.
+      #
+      # Media types are case-insensitive (RFC 9110 §8.3.1) but the registered
+      # ones are spelled in lower case and Rack matches them literally, so an
+      # `Accept: TEXT/PLAIN` found nothing and fell through to the default
+      # format — the client quietly got something other than what it asked for.
+      def self.format_for_accept(accept_header, mime_types)
+        return if accept_header.blank? || accept_header == ALL_MEDIA_TYPES
+
+        media_type = Rack::Utils.best_q_match(accept_header.downcase, mime_types.keys)
+        mime_types[media_type] if media_type
+      end
+
+      # +format_for_accept+ answers from the header and +mime_types+ alone. A
+      # client that names the format it wants sends one of those media types as
+      # it is registered (+application/json+), and most others send +*/*+ or
+      # nothing, so those answers are worked out once instead of re-running
+      # Rack's q-value match on every request. Any other header misses and is
+      # negotiated as before; only registered media types are keys, so a client
+      # cannot grow a table.
+      #
+      # Shared per +mime_types+, which Grape::ContentTypes already shares per
+      # content-type registry: every endpoint builds its own formatter.
+      class FormatForAcceptCache < Grape::Util::Cache
+        def initialize
+          super
+          @cache = Hash.new do |h, mime_types|
+            h[mime_types] = [*mime_types.keys, ALL_MEDIA_TYPES, nil].to_h { |accept| [accept, Formatter.format_for_accept(accept, mime_types)] }.freeze
+          end
+        end
+      end
+
       # The request methods that can carry a body worth parsing. See
-      # {#read_body_input?}, which tests the env against this before anything
-      # asks for a Rack::Request. QUERY is here because its content *is* the
-      # query (RFC 10008, Section 2), not an optional payload.
+      # {#body_given?}, which tests the env against this before anything asks
+      # for a Rack::Request. QUERY is here because its content *is* the query
+      # (RFC 10008, Section 2), not an optional payload.
       BODY_CARRYING_METHODS = [Rack::POST, Rack::PUT, Rack::PATCH, Rack::DELETE, Grape::QUERY].freeze
 
+      # The media types whose bodies Rack parses itself once the params are
+      # asked for, so the formatter leaves them alone.
+      #
+      # Tested against the media type the formatter parses anyway, rather than
+      # through Rack's +form_data?+ and +parseable_data?+, which parse
+      # CONTENT_TYPE again each. It is the same answer: +form_data?+ also holds
+      # for a POST with no media type, but Rack only finds none when
+      # CONTENT_TYPE is missing or empty, and a body like that was never left
+      # to Rack.
+      RACK_PARSED_MEDIA_TYPES = (Rack::Request::FORM_DATA_MEDIA_TYPES + Rack::Request::PARSEABLE_DATA_MEDIA_TYPES).freeze
+
       # Read off ivars rather than delegated into +config+ on every request:
       # +negotiate_content_type+ asks for +format+ and +default_format+ per
       # request and +fetch_formatter+ for +formatters+, and each delegator cost
@@ -36,60 +84,115 @@ module Grape
         @formatters = config.formatters
         @parsers = config.parsers
         mime_types
+        # Only an API that pins no format negotiates one from the Accept header.
+        @format_for_accept = FormatForAcceptCache[mime_types] unless format
+      end
+
+      # Base#call copies the middleware per request so #before and #after can
+      # keep the env and the app's response in ivars. The formatter keeps
+      # neither: it passes the env along and answers from the one instance the
+      # stack built.
+      def call(env)
+        call!(env).to_a
       end
 
-      def before
-        negotiate_content_type
-        read_body_input
+      def call!(env)
+        negotiated = negotiate_content_type(env)
+        read_body_input(env)
+        response = @app.call(env)
+        reporting_after_errors { format_response(env, response, negotiated) } || response
       end
 
-      def after
-        return unless @app_response
+      # Base's per-request readers look for the request in ivars that only a
+      # per-request copy sets, so the one instance the formatter answers from
+      # has none to give: +env+ is nil, +response+ raises, and +rack_request+
+      # would memoize a request on the instance every request shares.
+      private :env, :context, :rack_request, :query_params, :response
+
+      private
+
+      def format_response(env, response, negotiated)
+        return unless response
 
-        status, headers, bodies = @app_response
+        status, headers, bodies = response
 
         return [status, headers, []] if Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(status)
 
-        build_formatted_response(status, headers, bodies)
+        build_formatted_response(env, status, headers, bodies, negotiated)
       end
 
-      private
+      def build_formatted_response(env, status, headers, bodies, negotiated)
+        content_type_given = headers.key?(Rack::CONTENT_TYPE)
+        ensure_content_type!(env, headers)
+        return stream_response(status, headers, bodies) if bodies.is_a?(Grape::ServeStream::StreamResponse)
+
+        bodymap = format_bodies(env, headers, bodies)
+        # A formatter that renders a body only as Rack reads it (see
+        # Grape::Formatter::Jsonl) hands back a stream, served as +stream+'s is.
+        return stream_response(status, headers, bodymap.first) if bodymap.first.is_a?(Grape::ServeStream::StreamResponse)
+
+        # A bare Rack tuple rather than a Rack::Response: +headers+ is already
+        # a Grape::Util::Header (a Rack::Headers on Rack 3), so wrapping only
+        # re-normalizes the same keys into a second Headers hash that
+        # +Middleware::Base#call+ unwraps again with +to_a+ on the way out.
+        # The 204/304 bodies Rack::Response#finish would blank are returned
+        # by #format_response, before this point.
+        [status, headers, bodymap]
+      rescue Grape::Exceptions::InvalidFormatter => e
+        fallback = format_as_default(env, status, headers, bodies) if falls_back?(env, negotiated, content_type_given)
+        return fallback if fallback
 
-      def build_formatted_response(status, headers, bodies)
-        ensure_content_type!(headers)
+        throw :error, Grape::Exceptions::ErrorResponse.new(status: 500, message: e.message, backtrace: e.backtrace, original_exception: e)
+      end
 
-        if bodies.is_a?(Grape::ServeStream::StreamResponse)
-          Grape::ServeStream::SendfileResponse.new([], status, headers) do |resp|
-            resp.body = bodies.stream
-          end
-        else
-          # Allow content-type to be explicitly overwritten
-          formatter = fetch_formatter(headers)
-          bodymap = instrument_format_response(formatter) do
-            bodies.map { |body| formatter.call(body, env) }
-          end
-          # A bare Rack tuple rather than a Rack::Response: +headers+ is already
-          # a Grape::Util::Header (a Rack::Headers on Rack 3), so wrapping only
-          # re-normalizes the same keys into a second Headers hash that
-          # +Middleware::Base#call+ unwraps again with +to_a+ on the way out.
-          # The 204/304 bodies Rack::Response#finish would blank are returned
-          # above, before this point.
-          [status, headers, bodymap]
+      def format_bodies(env, headers, bodies)
+        # Picked by env['api.format']; the Content-Type header only counts when that is unset
+        formatter = fetch_formatter(env, headers)
+        instrument_format_response(env, formatter) do
+          bodies.map { |body| formatter.call(body, env) }
         end
-      rescue Grape::Exceptions::InvalidFormatter => e
-        throw :error, Grape::Exceptions::ErrorResponse.new(status: 500, message: e.message, backtrace: e.backtrace, original_exception: e)
+      end
+
+      def stream_response(status, headers, bodies)
+        Grape::ServeStream::SendfileResponse.new([], status, headers) do |resp|
+          resp.body = bodies.stream
+        end
+      end
+
+      # A format the client negotiated -- by its Accept header, the path's
+      # extension or +?format=+ -- that cannot render the body answers in the
+      # default format rather than 500. On an API that pins no format, a
+      # browser's Accept header and axios's both negotiate XML, which cannot
+      # render a String. The fallback applies only while the format is the
+      # client's alone: when the API pins one, or the endpoint set a
+      # Content-Type or another format itself, a body that does not fit is the
+      # endpoint's error and still answers 500.
+      def falls_back?(env, negotiated, content_type_given)
+        format.nil? && !content_type_given && env[Grape::Env::API_FORMAT] == negotiated
+      end
+
+      # Nil when the default format cannot render the body either.
+      def format_as_default(env, status, headers, bodies)
+        formatter = Grape::Formatter.formatter_for(default_format, formatters)
+        bodymap = bodies.map { |body| formatter.call(body, env) }
+        env[Grape::Env::API_FORMAT] = default_format.to_sym
+        headers.delete(Rack::CONTENT_TYPE)
+        ensure_content_type!(env, headers)
+        [status, headers, bodymap]
+      rescue Grape::Exceptions::InvalidFormatter
+        nil
       end
 
       # Guards on +listening?+ so that with no subscriber the payload Hash and
       # notification machinery are skipped and the block runs directly (no added
       # allocations); the block is forwarded anonymously.
-      def instrument_format_response(formatter, &)
+      def instrument_format_response(env, formatter, &)
         return yield unless ActiveSupport::Notifications.notifier.listening?('format_response.grape')
 
         ActiveSupport::Notifications.instrument('format_response.grape', formatter:, env:, &)
       end
 
-      def fetch_formatter(headers)
+      def fetch_formatter(env, headers)
         api_format = env.fetch(Grape::Env::API_FORMAT) { mime_types[headers[Rack::CONTENT_TYPE]] }
         Grape::Formatter.formatter_for(api_format, formatters)
       end
@@ -100,18 +203,26 @@ module Grape
       # this runs on every response, and copying the hash costs an allocation
       # per request for a header the caller is about to send anyway.
       #
+      # A format with no media type at all (see #media_type_for) leaves the
+      # header out: Rack forbids a nil header value.
+      #
       # @param headers [Hash] the response headers, mutated in place
       # @return [void]
-      def ensure_content_type!(headers)
+      def ensure_content_type!(env, headers)
         return if headers[Rack::CONTENT_TYPE]
 
-        headers[Rack::CONTENT_TYPE] = content_type_for(env[Grape::Env::API_FORMAT])
+        content_type = media_type_for(env[Grape::Env::API_FORMAT])
+        headers[Rack::CONTENT_TYPE] = content_type if content_type
       end
 
-      def read_body_input
-        return unless read_body_input?
+      def read_body_input(env)
+        return unless body_given?(env)
+
+        request = Rack::Request.new(env)
+        media_type = request.media_type
+        return if RACK_PARSED_MEDIA_TYPES.include?(media_type)
 
-        input = rack_request.body # reads RACK_INPUT
+        input = request.body # reads RACK_INPUT
         return if input.nil?
 
         rewind = input.respond_to?(:rewind)
@@ -119,17 +230,40 @@ module Grape
         input.rewind if rewind
         body = env[Grape::Env::API_REQUEST_INPUT] = input.read
         begin
-          read_rack_input(body)
+          read_rack_input(env, body, media_type)
         ensure
           input.rewind if rewind
         end
       end
 
-      def read_rack_input(body)
+      def read_rack_input(env, body, media_type)
         return if body.empty?
 
-        media_type = rack_request.media_type
+        parser = Grape::Parser.parser_for body_format(env, media_type), parsers
+        return env[Grape::Env::API_REQUEST_BODY] = body unless parser
 
+        begin
+          parsed = (env[Grape::Env::API_REQUEST_BODY] = parser.call(body, env))
+          merge_form_hash(env, parsed) if parsed.is_a?(Hash)
+        rescue ForeignParserError => e
+          throw :error, Grape::Exceptions::ErrorResponse.new(status: 400, message: e.message, backtrace: e.backtrace, original_exception: e)
+        end
+      end
+
+      # A body parsed into a Hash joins the form params Rack::Request reads,
+      # as a form body Rack parsed itself would.
+      def merge_form_hash(env, parsed)
+        if (form_hash = env[Rack::RACK_REQUEST_FORM_HASH])
+          form_hash.merge!(parsed)
+        else
+          env[Rack::RACK_REQUEST_FORM_HASH] = parsed
+        end
+        env[Rack::RACK_REQUEST_FORM_INPUT] = env[Rack::RACK_INPUT]
+      end
+
+      # The format a body of +media_type+ is read as, thrown as an error
+      # response when it cannot be read at all.
+      def body_format(env, media_type)
         # RFC 10008, Sections 2 and 2.1: a QUERY carries its query in the
         # content, so a request that never says what that content is cannot be
         # interpreted and must fail rather than be read as the default format.
@@ -137,50 +271,41 @@ module Grape
         throw :error, Grape::Exceptions::ErrorResponse.new(status: 400, message: 'The QUERY method requires a content-type.') if media_type.nil? && env[Rack::REQUEST_METHOD] == Grape::QUERY
 
         fmt = media_type ? mime_types[media_type] : default_format
-
         throw :error, Grape::Exceptions::ErrorResponse.new(status: 415, message: "The provided content-type '#{media_type}' is not supported.") unless content_type_for(fmt)
-        parser = Grape::Parser.parser_for fmt, parsers
-        return env[Grape::Env::API_REQUEST_BODY] = body unless parser
 
-        begin
-          parsed = (env[Grape::Env::API_REQUEST_BODY] = parser.call(body, env))
-          if parsed.is_a?(Hash)
-            if (form_hash = env[Rack::RACK_REQUEST_FORM_HASH])
-              form_hash.merge!(parsed)
-            else
-              env[Rack::RACK_REQUEST_FORM_HASH] = parsed
-            end
-            env[Rack::RACK_REQUEST_FORM_INPUT] = env[Rack::RACK_INPUT]
-          end
-        rescue Grape::Exceptions::Base => e
-          raise e
-        rescue StandardError => e
-          throw :error, Grape::Exceptions::ErrorResponse.new(status: 400, message: e.message, backtrace: e.backtrace, original_exception: e)
-        end
+        fmt
       end
 
-      # this middleware will not try to format the following content-types since Rack already handles them
-      # when calling Rack's `params` function
-      # - application/x-www-form-urlencoded
-      # - multipart/form-data
-      # - multipart/related
-      # - multipart/mixed
-      def read_body_input?
-        # Read off the env rather than through Rack::Request's predicates: this
-        # is what decides the question for every request, and on the GET, HEAD
-        # and OPTIONS majority it is the only thing the formatter would have
-        # built a Rack::Request for.
+      # What a parser raises that is not a Grape error, and so is answered as a
+      # 400 here. A Grape error goes on to the error middleware as it is. It
+      # used to be rescued just to be raised again, and re-raising at request
+      # depth cost about 25 µs -- paid by every malformed body, since the
+      # built-in parsers report one as InvalidMessageBody.
+      module ForeignParserError
+        def self.===(exception)
+          exception.is_a?(StandardError) && !exception.is_a?(Grape::Exceptions::Base)
+        end
+      end
+      private_constant :ForeignParserError
+
+      # Whether the request carries a body at all, read off the env alone. Every
+      # request asks, and the ones answered no -- the GET, HEAD and OPTIONS
+      # majority, and a POST or DELETE with nothing in it -- are answered before
+      # CONTENT_TYPE is parsed or a Rack::Request is built. The env key is
+      # spelled out: on Rack 3, +Rack::CONTENT_LENGTH+ names the response header.
+      def body_given?(env)
         return false unless BODY_CARRYING_METHODS.include?(env[Rack::REQUEST_METHOD])
-        return false if rack_request.form_data? && rack_request.content_type
-        return false if rack_request.parseable_data?
 
-        rack_request.content_length.to_i.positive? || env['HTTP_TRANSFER_ENCODING'] == 'chunked'
+        env['CONTENT_LENGTH'].to_i.positive? || env['HTTP_TRANSFER_ENCODING'] == 'chunked'
       end
 
-      def negotiate_content_type
-        fmt = format_from_extension || format_from_query || format || format_from_header || default_format
+      def negotiate_content_type(env)
+        fmt = format_from_extension(env) || format_from_query(env) || format || format_from_header(env) || default_format
         return env[Grape::Env::API_FORMAT] = fmt.to_sym if content_type_for(fmt)
 
+        synonym = declared_synonym(fmt)
+        return env[Grape::Env::API_FORMAT] = synonym if synonym
+
         throw :error, Grape::Exceptions::ErrorResponse.new(status: 406, message: "The requested format '#{fmt}' is not supported.")
       end
 
@@ -189,13 +314,24 @@ module Grape
       # sequence, and a +.+ byte cannot be part of a multi-byte one, so the dot
       # sits at the same place before and after scrubbing. The overwhelming
       # majority of paths carry no extension and now skip the scrub entirely.
-      def format_from_extension
-        request_path = path_for_extension
+      def format_from_extension(env)
+        request_path = path_for_extension(env)
         dot_pos = request_path.rindex('.')
         return unless dot_pos
 
-        extension = try_scrub(request_path[(dot_pos + 1)..])
-        extension if content_type_for(extension)
+        # A start and a length rather than an endless Range, which is an object
+        # of its own built on every call. A length past the end is clamped.
+        extension = try_scrub(request_path[dot_pos + 1, request_path.length])
+        return extension if content_type_for(extension)
+
+        declared_synonym(extension)
+      end
+
+      # The name the API declared +fmt+ under when the request used another
+      # one for it (see Grape::ContentTypes::FORMAT_SYNONYMS), or nil.
+      def declared_synonym(fmt)
+        synonym = Grape::ContentTypes::FORMAT_SYNONYMS[fmt]
+        synonym if synonym && content_type_for(synonym)
       end
 
       # The extension is the tail of the request path, so PATH_INFO answers it
@@ -205,32 +341,37 @@ module Grape
       # the String its concatenation allocates. Tested with +empty?+ rather
       # than +blank?+: the path is not scrubbed yet, and a regexp match on an
       # invalid byte sequence raises.
-      def path_for_extension
+      def path_for_extension(env)
         path_info = env[Rack::PATH_INFO]
-        return rack_request.path if path_info.nil? || path_info.empty?
+        return Rack::Request.new(env).path if path_info.nil? || path_info.empty?
 
         path_info
       end
 
       # +?format=+ can only be there when there is a query string at all, so
       # the common query-less request skips parsing one.
-      def format_from_query
+      #
+      # And a query string that spells neither +format+ nor a percent-escape
+      # cannot hold that key either: Rack splits the string on +&+ and +=+ and
+      # then unescapes each key, and unescaping only ever rewrites +%XX+ (or a
+      # +++, which becomes a space). So the parse -- the most expensive thing
+      # a request with a query string does, and one the endpoint may never ask
+      # for -- is left to whoever reads the params.
+      def format_from_query(env)
         query_string = env[Rack::QUERY_STRING]
         return if query_string.nil? || query_string.empty?
+        return unless query_string.include?(FORMAT_PARAM) || query_string.include?('%')
 
-        query_params['format']
+        Rack::Request.new(env).GET[FORMAT_PARAM]
+      rescue *Grape::RACK_ERRORS
+        raise Grape::Exceptions::RequestError
       end
 
-      # Media types are case-insensitive (RFC 9110 §8.3.1) but the registered
-      # ones are spelled in lower case and Rack matches them literally, so an
-      # `Accept: TEXT/PLAIN` found nothing and fell through to the default
-      # format — the client quietly got something other than what it asked for.
-      def format_from_header
-        accept_header = try_scrub(env['HTTP_ACCEPT'])
-        return if accept_header.blank? || accept_header == ALL_MEDIA_TYPES
-
-        media_type = Rack::Utils.best_q_match(accept_header.downcase, mime_types.keys)
-        mime_types[media_type] if media_type
+      # The keys are registered media types -- valid strings, which scrubbing
+      # leaves alone -- so only a miss needs the header scrubbed.
+      def format_from_header(env)
+        accept_header = env['HTTP_ACCEPT']
+        @format_for_accept.fetch(accept_header) { Formatter.format_for_accept(try_scrub(accept_header), mime_types) }
       end
     end
   end

data/lib/grape/middleware/precomputed_content_types.rb

@@ -4,7 +4,7 @@ module Grape
   module Middleware
     # Include in a middleware subclass that needs content-type negotiation.
     # Provides +content_types+ / +mime_types+ / +content_type_for+ /
-    # +content_type+ resolved from +config.content_types+ and
+    # +media_type_for+ / +content_type+ resolved from +config.content_types+ and
     # +config.format+ — so the consuming middleware's +Options+ Data class
     # must declare both fields. Warms those caches on the parent instance
     # at initialization so per-request +dup+s inherit them rather than
@@ -19,6 +19,9 @@ module Grape
     # Opt-in: plain +Grape::Middleware::Base+ subclasses that don't need
     # content-type-aware helpers don't pay for them.
     module PrecomputedContentTypes
+      # Grape's own media type for each built-in format, under both spellings.
+      DEFAULT_CONTENT_TYPES = Grape::ContentTypes.lookup_for(Grape::ContentTypes::DEFAULTS)
+
       def initialize(app, **options)
         super
         content_types
@@ -37,8 +40,17 @@ module Grape
         content_types_lookup[format]
       end
 
+      # The media type to label a response rendered in +format+ with: the one
+      # this API declares for it, or else Grape's own -- +api_format :txt+ in
+      # a +format :json+ API renders text/plain. #content_type_for stays nil
+      # for a format the API does not declare, since negotiation asks it
+      # whether the API supports the format at all.
+      def media_type_for(format)
+        content_type_for(format) || DEFAULT_CONTENT_TYPES[format]
+      end
+
       def content_type
-        content_type_for(env[Grape::Env::API_FORMAT] || config.format) || 'text/html'
+        media_type_for(env[Grape::Env::API_FORMAT] || config.format) || 'text/html'
       end
 
       private

data/lib/grape/middleware/stack.rb

@@ -80,14 +80,13 @@ module Grape
         middlewares.push(middleware)
       end
 
+      # Each spec ends in the block its operation was given, +nil+ when there
+      # was none. Telling the block apart by its class would take a Proc passed
+      # as the last argument, such as a callable the middleware is configured
+      # with, for the block.
       def merge_with(middleware_specs)
-        middleware_specs.each do |operation, klass, *args|
-          if args.last.is_a?(Proc)
-            last_proc = args.pop
-            public_send(operation, klass, *args, &last_proc)
-          else
-            public_send(operation, klass, *args)
-          end
+        middleware_specs.each do |operation, *args, block|
+          public_send(operation, *args, &block)
         end
       end
 
@@ -100,7 +99,7 @@ module Grape
       end
 
       # @description Add middlewares with :use operation to the stack. Store others with :insert_* operation for later
-      # @param [Array] other_specs An array of middleware specifications (e.g. [[:use, klass], [:insert_before, *args]])
+      # @param [Array] other_specs An array of middleware specifications (e.g. [[:use, klass, nil], [:insert_before, *args, block]])
       def concat(other_specs)
         use, not_use = other_specs.partition { |o| o.first == :use }
         others << not_use

data/lib/grape/middleware/versioner/base.rb

@@ -27,18 +27,30 @@ module Grape
 
         attr_reader :available_media_types, :error_headers, :versions
 
+        # Read off ivars rather than delegated through +version_options+ into
+        # +config+: the versioners ask for +vendor+, +strict+ or +parameter+ on
+        # every request, and each read went two Forwardable frames and two Data
+        # readers deep for a value fixed when the middleware was built.
+        attr_reader :cascade, :parameter, :strict, :vendor
+
         def_delegators :config, :mount_path, :prefix, :version_options
-        def_delegators :version_options, :cascade, :parameter, :strict, :vendor
 
         def initialize(app, **options)
           super
+          @cascade = version_options.cascade
+          @parameter = version_options.parameter
+          @strict = version_options.strict
+          # Media types are case-insensitive, and Grape::Util::MediaType parses
+          # an Accept header into lowercase; a vendor declared with capitals
+          # would otherwise never match one.
+          @vendor = version_options.vendor&.downcase
           @versions = config.versions&.map(&:to_s) # making sure versions are strings to ease potential match
           @error_headers = cascade ? CASCADE_PASS_HEADER : {}
           @available_media_types = build_available_media_types
         end
 
         def potential_version_match?(potential_version)
-          versions.blank? || versions.include?(potential_version)
+          versions.nil? || versions.empty? || versions.include?(potential_version)
         end
 
         def version_not_found!
@@ -50,15 +62,19 @@ module Grape
         def build_available_media_types
           media_types = []
           base_media_type = "application/vnd.#{vendor}"
-          versions&.reverse_each do |version|
-            versioned_base = "#{base_media_type}-#{version}"
-            content_types.each_key { |extension| media_types << "#{versioned_base}+#{extension}" }
-            media_types << versioned_base
-          end
-          content_types.each_key { |extension| media_types << "#{base_media_type}+#{extension}" }
-          media_types << base_media_type
+          versions&.reverse_each { |version| append_media_types(media_types, "#{base_media_type}-#{version}") }
+          append_media_types(media_types, base_media_type)
           media_types.concat(content_types.values.flatten)
-          media_types
+          # Media types are case-insensitive, and Grape::Util::MediaType matches
+          # an Accept header in lowercase; a version or content type declared
+          # with capitals would otherwise never match one.
+          media_types.map!(&:downcase)
+        end
+
+        # +base+ with each content type's extension, then +base+ alone.
+        def append_media_types(media_types, base)
+          content_types.each_key { |extension| media_types << "#{base}+#{extension}" }
+          media_types << base
         end
       end
     end