Answer a route opening with an optional segment without it under a namespace

A route's path is assembled by joining its mount path, prefix, version,
namespace and own path with slashes. A path opening with an optional
group, such as get '(:type)' inside namespace :root, compiled to
/root/(:type): the slash outside the group was required, and a request
path is normalized without a trailing slash, so /root answered 404. The
same went for a mount path, a prefix, a path version, and a slash
written in front of the group, as in get 'users/(:id)'.

The slash in front of an optional group now goes inside it, as
/root(/:type), the spelling that already worked when written out in
full. A slash opening the path stays where it is, so / still matches
/(:type).

Fixes #932.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ericproulx

CHANGELOG.md

@@ -19,6 +19,7 @@
 * [#3055](https://github.com/ruby-grape/grape/pull/3055): Stop a 405 behind `Rack::Cascade` from making the next app answer 405 too - [@ericproulx](https://github.com/ericproulx).
 * [#3058](https://github.com/ruby-grape/grape/pull/3058): Declare `rexml` in the test bundle instead of relying on Danger to bring it in - [@ericproulx](https://github.com/ericproulx).
 * [#3064](https://github.com/ruby-grape/grape/pull/3064): Cascade past a mounted Rack app that declines with a lowercase `x-cascade` - [@ericproulx](https://github.com/ericproulx).
+* [#XXXX](https://github.com/ruby-grape/grape/pull/XXXX): Answer a route opening with an optional segment without it under a namespace, prefix or mount path - [@ericproulx](https://github.com/ericproulx).
 * Your contribution here.
 
 ### 4.1.0 (2026-10-31)

UPGRADING.md

@@ -3,6 +3,13 @@ Upgrading Grape
 
 ### Upgrading to >= 4.2.0
 
+#### A path opening with an optional segment answers without it under a namespace
+
+A route path opening with an optional segment, such as `get '(:type)'` inside `namespace :root`, now also answers `/root` ([#XXXX](https://github.com/ruby-grape/grape/pull/XXXX)). Before, the slash Grape put between the namespace and the path was required, and a request path is never matched with a trailing slash, so `/root` answered `404`. The same goes for a mount path, a prefix, a path version, and a slash written in front of the segment, as in `get 'users/(:id)'`.
+
+* The route's `path` and `origin` move the slash into the segment: `/root(/:type)` instead of `/root/(:type)`. Anything reading them, such as API documentation, sees the new spelling.
+* A route declared after it for the path itself, such as `get` in the same namespace, no longer answers that path, as the earlier route now matches it first. Declare that route first, or drop it.
+
 #### A request every route declines answers 404, however many routes declined
 
 A route declines a request by answering with `X-Cascade: pass`, as a version declared with `cascade: true` does for a version it does not serve. As the [README](README.md#header) documents, the router then answers its own `404` if no other route takes the request. It only did so when one route had declined: with two or more routes on the path, the last one's response came back instead, and so did that of an ANY route (since 4.0.0). So a request for an unknown version answered `404` from an API with one version and `406` from an API with several.

lib/grape/router/pattern/path.rb

@@ -64,11 +64,22 @@ def valid_part?(part)
           part&.match?(/\A\S/) && not_slash?(part)
         end
 
+        # The parts are joined by slashes, so a path opening with an optional
+        # group under a namespace, mount path, prefix or version --
+        # +get '(:type)'+ in +namespace :root+ -- compiled to +/root/(:type)+.
+        # The slash outside the group is required, and a request path never
+        # ends in one, as it is normalized the way this one is: +/root+ matched
+        # nothing. Inside the group, the slash goes with the segment it
+        # separates, and +/root(/:type)+ answers +/root+ and +/root/x+ alike.
+        # A slash opening the path stays where it is, for +/+ to match
+        # +/(:type)+.
         class PartsCache < Grape::Util::Cache
+          SLASH_BEFORE_OPTIONAL_GROUP = %r{(?<=.)/\(/?}
+
           def initialize
             super
             @cache = Hash.new do |h, parts|
-              h[parts] = Grape::Util::PathNormalizer.call(parts.join('/'))
+              h[parts] = Grape::Util::PathNormalizer.call(parts.join('/')).gsub(SLASH_BEFORE_OPTIONAL_GROUP, '(/')
             end
           end
         end

spec/grape/api/optional_parameters_in_route_spec.rb

@@ -40,4 +40,101 @@ def app
       expect(last_response.body).to eq 'foo'
     end
   end
+
+  describe 'a path opening with an optional segment' do
+    %w[(:type) /(:type) (/:type)].each do |spelling|
+      context "when spelled #{spelling} in a namespace" do
+        subject do
+          Class.new(Grape::API) do
+            namespace(:root) { get(spelling) { "type=#{params[:type]}" } }
+          end
+        end
+
+        it 'answers the namespace path, with or without the segment' do
+          get '/root'
+          expect(last_response.body).to eq('type=')
+
+          get '/root/x'
+          expect(last_response.body).to eq('type=x')
+        end
+      end
+    end
+
+    context 'when it is a nested namespace' do
+      subject do
+        Class.new(Grape::API) do
+          namespace(:root) { namespace('(:type)') { get { "type=#{params[:type]}" } } }
+        end
+      end
+
+      it 'answers the outer namespace path, with or without the segment' do
+        get '/root'
+        expect(last_response.body).to eq('type=')
+
+        get '/root/x'
+        expect(last_response.body).to eq('type=x')
+      end
+    end
+
+    context 'when it follows a prefix and a path version' do
+      subject do
+        Class.new(Grape::API) do
+          prefix :api
+          version 'v1', using: :path
+          get('(:type)') { "type=#{params[:type]}" }
+        end
+      end
+
+      it 'answers the version path, with or without the segment' do
+        get '/api/v1'
+        expect(last_response.body).to eq('type=')
+
+        get '/api/v1/x'
+        expect(last_response.body).to eq('type=x')
+      end
+    end
+
+    context 'when it follows a mount path' do
+      subject do
+        things = Class.new(Grape::API) { get('(:type)') { "type=#{params[:type]}" } }
+        Class.new(Grape::API) { mount things => '/things' }
+      end
+
+      it 'answers the mount path, with or without the segment' do
+        get '/things'
+        expect(last_response.body).to eq('type=')
+
+        get '/things/x'
+        expect(last_response.body).to eq('type=x')
+      end
+    end
+
+    context 'when it follows a slash written in the same path' do
+      subject do
+        Class.new(Grape::API) { get('users/(:id)') { "id=#{params[:id]}" } }
+      end
+
+      it 'answers the path before it, with or without the segment' do
+        get '/users'
+        expect(last_response.body).to eq('id=')
+
+        get '/users/5'
+        expect(last_response.body).to eq('id=5')
+      end
+    end
+
+    context 'when it opens the path of the API' do
+      subject do
+        Class.new(Grape::API) { get('/(:type)') { "type=#{params[:type]}" } }
+      end
+
+      it 'answers the root, with or without the segment' do
+        get '/'
+        expect(last_response.body).to eq('type=')
+
+        get '/x'
+        expect(last_response.body).to eq('type=x')
+      end
+    end
+  end
 end

spec/grape/router/pattern/path_spec.rb

@@ -56,6 +56,11 @@ def path_settings(**attrs)
 
       expect(path.origin).to eql('/foo/hello/namespace/raw_path')
     end
+
+    it 'moves the slash in front of an optional group into it' do
+      path = described_class.new('(:type)', 'namespace', path_settings)
+      expect(path.origin).to eql('/namespace(/:type)')
+    end
   end
 
   describe '#suffix' do