Spring API Versioning with path segment strategy does not behave as expected

I currently test the new feature with Spring Web version 7.0.0-M8, and there are multiple issues I had before making it work. First of all, my sample code:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(@NonNull ApiVersionConfigurer configurer) {
        configurer
                .usePathSegment(1);
    }

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer
                .addPathPrefix("/api/{version}", HandlerTypePredicate.forAnnotation(RestController.class));
    }

}

@RestController
@RequestMapping("/hello")
public class MyController {

    @GetMapping(
            version = "1",
            produces = MediaType.TEXT_PLAIN_VALUE
    )
    public String sayHello() {
        return "Hello World";
    }

}

Missing Default

In Spring Boot, convention over configuration is one of the main concepts. But when I specify the version attribute in the controller, the app starts with an error message telling me to configure the versioning strategy. Maybe, there should be a default?

Lack of Documentation

A concrete sample would be nice for the different strategies, whereas header and query params are easier to understand than the path segment strategy. The Javadocs tell me, that there is a semantic versioning with 1.2+ syntax available, but it's not part of the reference documentation

I really had issues with the path seqment strategy, because the hint

[!NOTE] When using a path segment, consider configuring a shared path prefix externally in Path Matching options.

was not clear for me. A sample would be really nice here to clarify that this is recommended to add a {version} placeholder. Before getting this, I tried samples without any placeholder, because I thought this path segment would be added automatically to the routing. The second try was to add the placeholder to the @RequestMapping in the controller, which worked for me, but was not a good solution.

Additionally, I tried to use version = "1.0+", but I don't understand why the following samples bring an error response:

# works
GET http://localhost:8080/api/1/hello
GET http://localhost:8080/api/1.0/hello
# doesn't work
GET http://localhost:8080/api/1.0.1/hello
GET http://localhost:8080/api/1.1/hello

Error Responses and Logging

Without the {version} placeholder, I just got a 400 response status, without any message even in the dev mode. The console logs didn't show anything unless I changed the log level to debug. So when trying out, it was hard to detect where the problem is.

I'm not really lucky with the 400, would 404 be correct in case of a missing (or unavailable) version in the path?

Another Question

Would it be possible to get the concrete version injected into my controller's method? With that, we could do switches between versions programmatically instead of routing to different functions. Would be nice, to have this possibility too.

Comment From: rstoyanchev

Thanks for giving it a try and providing feedback.

Missing Default

There is no good default. It's not just about picking a name, but also the strategy which depends on the use case. A header or query parameter is better suited for lightweight API changes applied selectively to some endpoints but not all. The path is a more global across the application, which allows deeper structural change.

Lack of Documentation

The Javadocs tell me, that there is a semantic versioning with 1.2+ syntax available, but it's not part of the reference documentation

It's difficult to put all versioning information in one place, some of it belongs to controller mappings, some to functional endpoint mappings, some in config, and some more broadly for the underlying infrastructure. The link you reference is the config section, it contains further links. If you click on the link to ApiVersionParser there, it takes you here. I accept this wasn't easy enough to find, suggestions on how to improve welcome.

I really had issues with the path seqment strategy

I see where you struggled. This really needs to be expanded on. I've created #35421.

Additionally, I tried to use version = "1.0+", but I don't understand why the following samples bring an error response

I'm guessing that versions 1.0.1 and 1.1 are not known as "supported" versions. Either they need to be present somewhere in request mappings, or added as supported versions in the config.

Error Responses and Logging

Without the {version} placeholder, I just got a 400 response status, without any message even in the dev mode.

Generally, by default we don't send error details, but this is possible to customize. Possibly Boot might be able to help but I'm not sure.

I'm not really lucky with the 400, would 404 be correct

For consistency it makes sense to raise the same always, and a 404 could only possibly be applicable to the path strategy. In any case a 404 would make it even more opaque to know what went wrong.

Another Question

Would it be possible to get the concrete version injected into my controller's method?

There is nothing for that at the moment, but the version is stored in the request attribute HandlerMapping.API_VERSION_ATTRIBUTE, so it's possible to get as an @RequestAttribute (for this you'll need a constant somewhere with the full request attribute name).

I've created #35424 to see what we can do. In the very least we can support the version type parsed by default.