Update documentation on trailing slash handling where type-level @GetMapping("/base") is combined with method level @GetMapping("/")

[gustavovnicius]

When using UrlHandlerFilter.trailingSlashHandler() to restore the deprecated trailing slash behavior, requests are not properly handled for endpoints that explicitly define @GetMapping("/") under a @RequestMapping base path.

Expected behavior:
Both /base-path and /base-path/ should return a successful response when using the trailing slash handler filter.

Actual behavior:
Neither /base-path nor /base-path/ works - both return 404. The endpoint is not registered at all when the controller method is annotated with @GetMapping("/"). If the filter is not applied, then the path with trailing slash works, but when applied, neither works.

Minimal reproduction:

@RestController
@RequestMapping("/base-path")
static class SegmentedTestController {
    // This does NOT work - both /base-path and /base-path/ return 404
    @GetMapping("/")
    public String getBasePath() {
        return "base-path";
    }
}

Workaround:

@RestController
@RequestMapping("/base-path")
static class SegmentedTestController {
    // This WORKS - /base-path returns 200, /base-path/ also works with filter
    @GetMapping
    public String getBasePath() {
        return "base-path";
    }
}

Filter configuration:

@Bean
UrlHandlerFilter trailingSlashRedirectFilter() {
    return UrlHandlerFilter.trailingSlashHandler("/**")
            .wrapRequest()
            .build();
}

Environment:

• Spring Framework version: tested with 6.2.x and 7.0x

Analysis:
It appears that @GetMapping("/") combined with @RequestMapping("/base-path") does not properly register the endpoint, whereas @GetMapping (without the explicit / value) does. The deprecated setUseTrailingSlashMatch(true) behavior handled both cases identically.

[rstoyanchev]

In effect you have a mapping with a trailing slash "/base-bath/" while the filter removes the trailing slash from the request path, so this is expected. Either the mapping should be without a trailing slash, or the filter should not apply to this path.

[gustavovnicius]

Thank you for the quick reply @rstoyanchev. I understand the technical reasoning behind the current behavior.

However, I'd like to point out that this represents a behavioral difference from the deprecated PathMatchConfigurer.setUseTrailingSlashMatch(true), which handled @GetMapping("/") under a @RequestMapping base path without issues. Both /base-path and /base-path/ would resolve correctly.

The current UrlHandlerFilter documentation states:

"In previous Spring Framework versions, Spring MVC could be configured to ignore trailing slashes in URL paths when mapping incoming requests on controller methods. This means that sending a 'GET /home/' request would be handled by a controller method annotated with @GetMapping('/home')."

This suggests UrlHandlerFilter is the migration path for the deprecated behavior. However, the documentation doesn't mention that @GetMapping("/") combined with a @RequestMapping base path behaves differently than @GetMapping - a pattern that worked transparently with the old setUseTrailingSlashMatch(true).

So it seems there are two options:

1. Fix the documentation: Explicitly note that @GetMapping("/") under a @RequestMapping creates a mapping with a trailing slash (/base-path/), and that such mappings should be changed to @GetMapping (without the explicit /) when migrating to preserve the previous behavior.

2. Fix the behavior: Have UrlHandlerFilter handle this edge case to provide full compatibility with the deprecated setUseTrailingSlashMatch(true) behavior it's meant to replace.

Either way, the current state leaves a gap between the documented migration path and the actual behavior for users with this pattern in their codebase.

[rstoyanchev]

UrlHandlerFilter is not aware of controller mappings, and not in a good position to fix this. Even if the original request path is exposed for mapping purposes, it would bring back the possibility for a mismatch between security decisions made earlier vs controller mappings. This would be fragile and it would stop working if you switch from request wrapping to a redirect.

I get the argument the mapping used to work, but I see the filter as more as an alternative to migrate to rather than a full guarantee that nothing would need to change. It's the combination of both the mapping (with or without a trailing slash) and the filter configuration (what it filters vs not).

I do get that the case confusing and based on something less than obvious. It is a good idea to call it out explicitly in the reference documentation and in JavaDoc, so I'll schedule it to do that.

Thanks for bringing this up.