Spring Boot 2.6.0 introduced various updates and improvements, but it also led to some compatibility issues with certain libraries. One of the common issues developers encounter is the failure to start the bean documentationPluginsBootstrapper when using Springfox 3 with Spring Boot 2.6. In this article, we will explore the problem in detail and provide possible solutions and workarounds.

Understanding the Problem

Springfox is a popular library for generating API documentation in Spring-based applications. The documentationPluginsBootstrapper is a Springfox bean responsible for bootstrapping documentation plugins. When the application starts, Spring initializes this bean to generate API documentation.

Key Error Message

Developers facing this issue usually see an error message resembling the following:

Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
...
The bean 'documentationPluginsBootstrapper', defined in URL [jar:file:/path/to/springfox-core-3.0.0.jar!/springfox/documentation/spring/web/plugins/DocumentationPluginsBootstrapper.class], could not be registered. A bean with that name has already been defined.

Root Cause Analysis

The primary cause of this issue is the changes in Spring Boot 2.6.0's internal handling of application contexts and bean registration. These changes disrupt the expected initialization flow of Springfox, leading to bean conflicts.

Important Changes in Spring Boot 2.6.0

• Path Matching Strategy: Spring Boot 2.6 introduced changes in the default path matching strategy. Instead of using PathPatternParser, it now defaults to AntPathMatcher, which is incompatible with Springfox out of the box.
• Spring Boot Properties Binding: The change affects Springfox’s initialization, leading to circular dependencies or initialization errors.

Bean Incompatibility

Spring's dependency and bean registration policies became stricter in 2.6.0, able to detect multiple beans matching certain type signatures, which results in conflicts for some pre-existing libraries like Springfox.

Workarounds and Solutions

While a permanent fix may require updates to Springfox, you can apply several workarounds to resolve the conflict:

1. Configure Path Matching Compatibility

Modify your application.properties or application.yml to maintain compatibility with Springfox by using the legacy path matcher:

spring.mvc.pathmatch.matching-strategy=ant-path-matcher

2. Exclude Certain Auto Configurations

Explicitly exclude problematic auto-configurations from Spring Boot that conflict with Springfox:

1@SpringBootApplication(exclude = {
2    WebMvcAutoConfiguration.class
3})
4public class MyApplication {
5    public static void main(String[] args) {
6        SpringApplication.run(MyApplication.class, args);
7    }
8}

3. Use Springfox via Spring Boot Starter

Switching to springdoc-openapi, a similar library fully compatible with Spring Boot 2.6, can be a more permanent solution.

1<dependency>
2    <groupId>org.springdoc</groupId>
3    <artifactId>springdoc-openapi-ui</artifactId>
4    <version>1.5.13</version>
5</dependency>

4. Custom Bean Definitions

Manually define any conflicting beans in your application context to avoid automatic bean registration issues:

1@Bean
2public DocumentationPluginsBootstrapper documentationPluginsBootstrapper() {
3    return new DocumentationPluginsBootstrapper(...);
4}

Summary Table

Additional Resources

• Official Guides: Read the Spring Fox Documentation for more details.
• Spring Boot Upgrade Notes: Acquaint yourself with Spring Boot 2.6.0 Release Notes for an overview of compatibility changes.

These insights and workarounds should help you circumvent the initialization issue with Springfox and Spring Boot 2.6.0, ensuring your application documentation is generated correctly without delays or downtime.