Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/spring-projects/spring-boot/llms.txt

Use this file to discover all available pages before exploring further.

Spring Boot’s auto-configuration mechanism inspects your classpath, the beans you have already defined, and various property settings to automatically configure the Spring application context on your behalf. When HSQLDB is on the classpath and you have not registered a DataSource bean yourself, Spring Boot configures an in-memory database without you writing a single line of configuration.

​
Enabling auto-configuration

Auto-configuration is opt-in. You activate it by placing @EnableAutoConfiguration or @SpringBootApplication on one of your @Configuration classes. 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}
@SpringBootApplication is a convenience annotation that combines three annotations in one:

@SpringBootConfiguration

Marks the class as a configuration source and enables detection in integration tests.

@EnableAutoConfiguration

Activates Spring Boot’s auto-configuration import selector, which loads all registered auto-configurations.

@ComponentScan

Scans the package of the annotated class and its sub-packages for Spring components.
Add only one @SpringBootApplication or @EnableAutoConfiguration annotation per application — place it on your primary @Configuration class.

​
How conditions control auto-configuration

Each auto-configuration class is a regular @Configuration class annotated with one or more @Conditional annotations. Spring Boot evaluates these conditions at startup and only applies an auto-configuration when all its conditions are met. The three most commonly used condition annotations are:
Applies the configuration only when specified classes are present on the classpath.
@AutoConfiguration
public class MyAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(SomeService.class)
    public static class SomeServiceConfiguration {

        @Bean
        @ConditionalOnMissingBean
        public SomeService someService() {
            return new SomeService();
        }

    }

}
When using @ConditionalOnClass on a @Bean method, isolate the condition in a nested @Configuration class. Otherwise the JVM may load and process the method’s return type before the condition is evaluated, causing a ClassNotFoundException at startup.
Applies the configuration only when no bean of the specified type is already registered in the BeanFactory. This is what allows you to override auto-configured beans by defining your own.
@Configuration
public class MyAutoConfiguration {

    @ConditionalOnMissingBean
    @Bean
    public MyService myService() {
        // ...
    }

}
The condition checks only the bean definitions processed so far, so it is strongly recommended to use @ConditionalOnMissingBean only within auto-configuration classes.
Applies the configuration only when a specified property has a given value (or is simply present and not set to false).
@AutoConfiguration
@ConditionalOnBooleanProperty(name = "spring.aop.auto", matchIfMissing = true)
public final class AopAutoConfiguration {
    // ...
}
The matchIfMissing attribute controls the outcome when the property is absent from the environment.

​
Gradually replacing auto-configuration

Auto-configuration is non-invasive. The moment you register your own bean of a type that auto-configuration would have provided, the auto-configured bean backs away. For example, if you define your own DataSource bean, the embedded database auto-configuration no longer applies. To understand which auto-configurations are currently active and why, start your application with the --debug flag: 
$ java -jar myapp.jar --debug
This prints a conditions evaluation report to the console, listing each auto-configuration class along with the condition that matched or did not match.

​
Disabling specific auto-configurations

If a particular auto-configuration is being applied and you do not want it, use the exclude attribute of @SpringBootApplication: 
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication {
    // ...
}
When the class is not on the classpath, use the excludeName attribute with the fully qualified class name instead: 
@SpringBootApplication(excludeName = { "org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration" })
public class MyApplication {
    // ...
}
You can also exclude auto-configurations via a property, which is useful when you cannot modify the source code: 
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
Even though auto-configuration classes are public, only the class name is considered public API. The internal contents — nested configuration classes and bean methods — are not meant to be used directly.

​
Writing your own auto-configuration

1

Create the auto-configuration class

Annotate your class with @AutoConfiguration instead of @Configuration. This is a composed annotation that sets proxyBeanMethods = false and participates in the auto-configuration ordering mechanism.
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
@ConditionalOnClass(SomeService.class)
public class SomeServiceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public SomeService someService() {
        return new SomeService();
    }

}
2

Register the auto-configuration class

Create a file at META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports in your jar and list your auto-configuration class name:
com.example.SomeServiceAutoConfiguration
Spring Boot loads this file using ImportCandidates at startup.
3

Control ordering if needed

Use @AutoConfiguration(before = ...) or @AutoConfiguration(after = ...) to declare ordering relationships with other auto-configuration classes:
@AutoConfiguration(after = DataSourceAutoConfiguration.class)
public class SomeServiceAutoConfiguration {
    // ...
}

​
Auto-configuration packages

The package of the class annotated with @EnableAutoConfiguration (typically your main application class) becomes the default auto-configuration package. Auto-configured features such as JPA entity scanning and Spring Data repository scanning look in this package by default. You can register additional packages using @AutoConfigurationPackage: 
import org.springframework.boot.autoconfigure.AutoConfigurationPackage;
import org.springframework.context.annotation.Configuration;

@Configuration
@AutoConfigurationPackage
public class AdditionalPackageConfiguration {
    // ...
}

Build docs developers (and LLMs) love

Get started for freeTalk to us