Spring Framework 7 API Versioning

Code Comparison

// Version 1 controller
@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 {
    @GetMapping("/{id}")
    public ProductDtoV1 getProduct(
            @PathVariable Long id) {
        return service.getV1(id);
    }
}

// Version 2 — duplicated structure
@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 {
    @GetMapping("/{id}")
    public ProductDtoV2 getProduct(
            @PathVariable Long id) {
        return service.getV2(id);
    }
}

// Configure versioning once
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(
            ApiVersionConfigurer config) {
        config.useRequestHeader("X-API-Version");
    }
}

// Single controller, version per method
@RestController
@RequestMapping("/api/products")
public class ProductController {
    @GetMapping(value = "/{id}", version = "1")
    public ProductDtoV1 getV1(@PathVariable Long id) {
        return service.getV1(id);
    }

    @GetMapping(value = "/{id}", version = "2")
    public ProductDtoV2 getV2(@PathVariable Long id) {
        return service.getV2(id);
    }
}

Why the modern way wins

🗂️

No controller duplication

All versions live in one controller class; only the individual handler methods carry a version attribute.

⚙️

Centralised version strategy

Switch from header to URL or query-param versioning in a single configureApiVersioning call.

📈

Incremental evolution

Add a new version to one method without touching unrelated endpoints or creating new controller files.

Old Approach

Manual URL Path Versioning

Modern Approach

Native API Versioning

JDK Support

Spring Framework 7 API Versioning

Available

Available since Spring Framework 7.0 (requires Java 17+)

How it works

Before Spring Framework 7, API versioning required separate controller classes per version (e.g., /api/v1/products, /api/v2/products), duplicating request mappings and scattering version logic across many files. Spring Framework 7 introduces native versioning through a new version attribute on @RequestMapping and related annotations, plus a configureApiVersioning hook in WebMvcConfigurer. The version can be resolved from a request header, a URL path segment, or a query parameter — all controlled in one place.