Skip to main content

Spring Boot 4.0 migration

This document describes the historical changes made to migrate the provider data API (persistent) from Spring Boot 3.5 to Spring Boot 4.0.

Changes summary

The following dependency changes were made at the time of migration (note that some of these dependencies have been updated subsequently).

Component Before After
LAA Spring Boot Gradle plugin 1.2.2 2.0.4
Spring Boot 3.5.7 4.0.1 (via plugin)
SpringDoc OpenAPI 2.8.12 3.0.1
WebMVC starter spring-boot-starter-web spring-boot-starter-webmvc
Modularised test starters spring-boot-starter-test webmvc-test, data-jpa-test
Test annotation packages o.s.b.test.autoconfigure.web.servlet.* o.s.b.webmvc.test.autoconfigure.*
ProblemDetail test assertions Exact string matching jsonPath field assertions

Code changes

LAA plugin version

Reference: LAA Spring Boot Common release notes \ Files changed: **/build.gradle

id 'uk.gov.laa.springboot.laa-spring-boot-gradle-plugin' version '2.0.4'

Upgrading the plugin upgraded Spring Boot to 4.0.1, which also upgraded related frameworks (Spring Framework 7.x, Spring Security 7.x, Spring Data 2025.x).

Web starter renamed

Reference: Web Application Starters \ Files changed: **/build.gradle

// Spring Boot 4.0 modularisation renamed this starter
implementation 'org.springframework.boot:spring-boot-starter-webmvc'

SpringDoc OpenAPI

Reference: SpringDoc compatibility matrix \ Files changed: **/build.gradle

// Spring Boot 4.0 requires SpringDoc 3.x
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.1'

Test starters modernised

Reference: Test Starters \ Files changed: **/build.gradle

// Spring Boot 4.0 encourages modular test dependencies
testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
testImplementation 'org.springframework.boot:spring-boot-starter-data-jpa-test'

Test annotation package changes

Reference: Test Starters \ Files changed: **/src/test/**/*.java and **/src/integrationTest/**/*.java

Spring Boot 4.0’s modularisation moved web MVC test annotations to a new package structure.

// Before (Spring Boot 3.5):
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

// After (Spring Boot 4.0):
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;

ProblemDetail test assertions

Reference: Problem Details \ Files changed: **/src/test/**/*.java and **/src/integrationTest/**/*.java

Spring Boot 4.0 changed ProblemDetail JSON serialisation (Jackson 3 + RFC 7807):

  • The type field may be omitted when it has the value about:blank
  • JSON property order is no longer guaranteed (and has changed)
// Before: brittle - exact string matching 
.andExpect(content().string("{\"type\":\"about:blank\",\"title\":\"Bad Request\"," +
    "\"status\":400,\"detail\":\"Invalid request content.\",\"instance\":\"/api/v1/items\"}"));

// After: resilient - individual field assertions
.andExpect(jsonPath("$.title").value("Bad Request"))
.andExpect(jsonPath("$.status").value(400))
.andExpect(jsonPath("$.detail").value("Invalid request content."))
.andExpect(jsonPath("$.instance").value("/api/v1/items"));

What was not changed

Jackson dependency

Reference: Jackson 3 Upgrading Guide

The codebase still used com.fasterxml.jackson.* imports (Jackson 2) immediately after migration, which was correct and intentional. Spring Boot 4.0 supports the coexistence of both Jackson 2 and Jackson 3 simultaneously.

Spring Boot’s autoconfigured ObjectMapper uses Jackson 3 (tools.jackson.*), whereas application code and OpenAPI-generated classes use Jackson 2 (com.fasterxml.jackson.*). Both versions coexist safely without requiring code changes at the time of migration.

  • Jackson annotations remain in com.fasterxml.jackson.annotation.* even in Jackson 3
  • Java 8 time types (java.time.*) are built into Jackson 3 core (no separate jackson-datatype-jsr310 needed)
  • The com.fasterxml.jackson.* (Jackson 2) → tools.jackson.* (Jackson 3) migration can happen gradually

OpenAPI generator config

References: Plugin compatibility, OpenAPI generator issue

The useSpringBoot3: "true" flag is Jakarta EE-based and remains compatible with Spring Boot 4.0. The OpenAPI generator currently generates Jackson 2 based code, which is fine (but deprecated). See previous section on the Jackson dependency.

Build and runtime platform changes

Reference: Review system requirements

The build already used Java 25 and Gradle 9.2.0 at the time of migration, which were ahead of Spring Boot 4.0’s minimum requirements of Java 17+ and Gradle 8.14+, so no change was needed.

Test code structure

Reference: Upgrading testing features

The test code structure (use of annotations and test patterns) was already Spring Boot 4.0 compliant:

  • Integration tests already used @AutoConfigureMockMvc annotation
  • Unit tests used @WebMvcTest annotation and @MockitoBean

However, the annotation imports required updating (see test annotation package changes above).

References