Master Spring 7 API Versioning: Hands‑On Guide with Real‑World Code

Introduction

Spring Boot 3 practical case collection now includes over 100 real‑world articles and promises permanent updates. Subscribers receive the complete source code and detailed MD notes to aid learning.

Practical Example: API Versioning in Spring 7

Spring 7.0.0‑M3 introduces built‑in support for API version definition. This guide demonstrates how to quickly try the feature.

1. Environment Preparation

<properties>
  <spring.version>7.0.0-M3</spring.version>
</properties>

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-context</artifactId>
  <version>${spring.version}</version>
</dependency>

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-web</artifactId>
  <version>${spring.version}</version>
</dependency>

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-webmvc</artifactId>
  <version>${spring.version}</version>
</dependency>

Configure the milestone repository to download the snapshot:

<repositories>
  <repository>
    <id>spring-milestones</id>
    <name>Spring Milestones</name>
    <url>https://repo.spring.io/milestone</url>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

2. Configure Web Environment

Implement WebApplicationInitializer to register the Spring container and DispatcherServlet:

public class PackWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
  @Override
  protected Class<?>[] getRootConfigClasses() {
    return new Class<?>[] { RootConfig.class };
  }

  @Override
  protected Class<?>[] getServletConfigClasses() {
    return new Class<?>[] { WebConfig.class };
  }

  @Override
  protected String[] getServletMappings() {
    return new String[] { "/*" };
  }
}

Root configuration class:

@Configuration
@ComponentScan({"com.pack.service", "com.pack.repository"})
public class RootConfig {
}

Web configuration class:

@Configuration
@EnableWebMvc
@ComponentScan({"com.pack.controller"})
public class WebConfig {
}

3. API Version Configuration

Create a custom version resolver that reads the v request parameter:

public class PackWebMvcConfigurer implements WebMvcConfigurer {
  @Override
  public void configureApiVersioning(ApiVersionConfigurer configurer) {
    configurer.useVersionResolver(new ApiVersionResolver() {
      @Override
      public @Nullable String resolveVersion(HttpServletRequest request) {
        return request.getParameter("v");
      }
    });
  }
}

If no ApiVersionResolver is provided, the application will fail to start.

4. Define Controller Interfaces

Use the new version attribute on @RequestMapping (or @GetMapping) to bind a method to a specific API version:

@RestController
@RequestMapping("/api")
public class ApiController {

  @GetMapping(value = "/query", version = "1.0.0")
  public ResponseEntity<Object> queryV1() {
    return ResponseEntity.ok("query api v1.0.0...");
  }

  @GetMapping(value = "/query", version = "2.0.0")
  public ResponseEntity<Object> queryV2() {
    return ResponseEntity.ok("query api v2.0.0...");
  }
}

Requests with an undefined version will throw InvalidApiVersionException.

Conclusion

This article demonstrates the new API versioning feature introduced in Spring 7.0.0‑M3, providing a complete Maven setup, web environment configuration, custom resolver, and versioned controller examples. The Spring Boot 3 case collection remains available for further learning.

For more detailed implementations, see the linked articles on multi‑version API control and custom annotation management.