How to Upgrade Spring Boot to 2.6.x Without Circular Dependency and Swagger Issues

Talk About Spring Boot Versions

The latest Spring Boot release is 2.6.4. Version 2.7.x is upcoming, while 2.4.x and earlier are no longer maintained. The mainstream versions are now 2.5.x and 2.6.x.

Upgrade Process

We upgraded the mall-tiny-swagger project to Spring Boot 2.6.4 and encountered several pitfalls.

Add Dependency

Update the Spring Boot version in pom.xml from 2.4.x to 2.6.4. Note that the .RELEASE suffix is no longer used.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.4</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

Circular Dependency

After starting the application, SecurityConfig and UmsAdminServiceImpl reference each other, causing a circular dependency.

The chain involves SecurityConfig → UmsAdminService → PasswordEncoder and back.

Quick fix: enable circular references in application.yml (crude).

spring:
  main:
    allow-circular-references: true

Better fix: use @Lazy on one of the beans (e.g., lazily load UmsAdminService inside SecurityConfig).

Startup Error (Swagger)

After the upgrade, Swagger throws a NullPointerException. Adding a custom BeanPostProcessor resolves the issue.

/**
 * Swagger2 API documentation configuration
 */
@Configuration
public class Swagger2Config {

    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {
            @Override
            public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
                if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
                    customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                }
                return bean;
            }

            private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
                List<T> copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }

            @SuppressWarnings("unchecked")
            private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                    field.setAccessible(true);
                    return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                } catch (IllegalArgumentException | IllegalAccessException e) {
                    throw new IllegalStateException(e);
                }
            }
        };
    }
}

Documentation Not Displayed

Swagger UI fails because Spring MVC’s default path‑matching strategy changed to PATH_PATTERN_PARSER. Switch it back to ANT_PATH_MATCHER in application.yml.

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

Talk About Springfox

Springfox provides Swagger integration for Spring Boot, but its latest release is 3.0.0 from two years ago, and compatibility may degrade as Spring Boot evolves.

Summary

We upgraded a Spring Boot project to the 2.6.x line, solved circular dependency issues with @Lazy or by allowing circular references, and restored Swagger functionality by adding a custom BeanPostProcessor and switching the MVC path‑matching strategy.

References

Official site: https://github.com/springfox/springfox

Project Source Code

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-swagger2