Versionamento de API no Spring Framework 7
Substitua controllers duplicados com prefixo de versão pelo suporte nativo de versionamento de API do Spring Framework 7.
// 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);
}
}
Sem duplicação de controllers
Todas as versões ficam em uma única classe de controller; apenas os métodos handler individuais carregam o atributo version.
Estratégia de versão centralizada
Alterne entre versionamento por header, URL ou query-param em uma única chamada configureApiVersioning.
Evolução incremental
Adicione uma nova versão a um método sem alterar endpoints não relacionados ou criar novos arquivos de controller.
Disponível desde o Spring Framework 7.0 (requer Java 17+)
Antes do Spring Framework 7, o versionamento de API exigia classes de controller separadas por versão (ex. /api/v1/products, /api/v2/products), duplicando mapeamentos de requisição e espalhando a lógica de versão por muitos arquivos. O Spring Framework 7 introduz versionamento nativo através de um novo atributo version em @RequestMapping e anotações relacionadas, além de um hook configureApiVersioning no WebMvcConfigurer. A versão pode ser resolvida a partir de um header de requisição, um segmento de caminho URL ou um parâmetro de query — tudo controlado em um único lugar.