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

<code>&lt;properties&gt;
  &lt;spring.version&gt;7.0.0-M3&lt;/spring.version&gt;
&lt;/properties&gt;

&lt;dependency&gt;
  &lt;groupId&gt;org.springframework&lt;/groupId&gt;
  &lt;artifactId&gt;spring-context&lt;/artifactId&gt;
  &lt;version&gt;${spring.version}&lt;/version&gt;
&lt;/dependency&gt;

&lt;dependency&gt;
  &lt;groupId&gt;org.springframework&lt;/groupId&gt;
  &lt;artifactId&gt;spring-web&lt;/artifactId&gt;
  &lt;version&gt;${spring.version}&lt;/version&gt;
&lt;/dependency&gt;

&lt;dependency&gt;
  &lt;groupId&gt;org.springframework&lt;/groupId&gt;
  &lt;artifactId&gt;spring-webmvc&lt;/artifactId&gt;
  &lt;version&gt;${spring.version}&lt;/version&gt;
&lt;/dependency&gt;</code>

Configure the milestone repository to download the snapshot:

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

2. Configure Web Environment

Implement WebApplicationInitializer to register the Spring container and DispatcherServlet :

<code>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[] { "/*" };
  }
}</code>

Root configuration class:

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

Web configuration class:

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

3. API Version Configuration

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

<code>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");
      }
    });
  }
}</code>

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:

<code>@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...");
  }
}
</code>

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.