diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc index 60388e7497..56e6625ed3 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc @@ -344,14 +344,16 @@ reversed domain name (for example, `com.example.project`). [[using-boot-locating-the-main-class]] === Locating the Main Application Class We generally recommend that you locate your main application class in a root package -above other classes. The `@EnableAutoConfiguration` annotation is often placed on your -main class, and it implicitly defines a base "`search package`" for certain items. For -example, if you are writing a JPA application, the package of the -`@EnableAutoConfiguration` annotated class is used to search for `@Entity` items. +above other classes. The <> is often placed on your main class, and it +implicitly defines a base "`search package`" for certain items. For example, if you are +writing a JPA application, the package of the `@SpringBootApplication` annotated class +is used to search for `@Entity` items. Using a root package also allows component +scan to apply only on your project. -Using a root package also lets the `@ComponentScan` annotation be used without needing to -specify a `basePackage` attribute. You can also use the `@SpringBootApplication` -annotation if your main class is in the root package. +TIP: If you don't want to use `@SpringBootApplication`, the `@EnableAutoConfiguration` +and `@ComponentScan` annotations that it imports defines that behaviour so you can also +use that instead. The following listing shows a typical layout: @@ -376,20 +378,16 @@ The following listing shows a typical layout: ---- The `Application.java` file would declare the `main` method, along with the basic -`@Configuration`, as follows: +`@SpringBootApplication`, as follows: [source,java,indent=0] ---- package com.example.myapplication; import org.springframework.boot.SpringApplication; - import org.springframework.boot.autoconfigure.EnableAutoConfiguration; - import org.springframework.context.annotation.ComponentScan; - import org.springframework.context.annotation.Configuration; + import org.springframework.boot.autoconfigure.SpringBootApplication - @Configuration - @EnableAutoConfiguration - @ComponentScan + @SpringBootApplication public class Application { public static void main(String[] args) { @@ -441,8 +439,9 @@ then Spring Boot auto-configures an in-memory database. You need to opt-in to auto-configuration by adding the `@EnableAutoConfiguration` or `@SpringBootApplication` annotations to one of your `@Configuration` classes. -TIP: You should only ever add one `@EnableAutoConfiguration` annotation. We generally -recommend that you add it to your primary `@Configuration` class. +TIP: You should only ever add one `@SpringBootApplication` or `@EnableAutoConfiguration` +annotation. We generally recommend that you add one or the other to your primary +`@Configuration` class only. @@ -546,11 +545,16 @@ TIP: Notice how using constructor injection lets the `riskAssessor` field be mar [[using-boot-using-springbootapplication-annotation]] == Using the @SpringBootApplication Annotation -Many Spring Boot developers always have their main class annotated with `@Configuration`, -`@EnableAutoConfiguration`, and `@ComponentScan`. Since these annotations are so -frequently used together (especially if you follow the -<> above), Spring Boot provides a -convenient `@SpringBootApplication` alternative. +Many Spring Boot developers like their apps to use auto-configuration, component scan and +be able to define extra configuration on their "application class". A single +`@SpringBootApplication` annotation can be used to enable those tree features, that is: + +* `@EnableAutoConfiguration`: enable <> +* `@ComponentScan`: enable `@Component` scan on the package where the application is +located (see <>) +* `@Configuration`: allow to register extra beans in the context or import additional +configuration classes The `@SpringBootApplication` annotation is equivalent to using `@Configuration`, `@EnableAutoConfiguration`, and `@ComponentScan` with their default attributes, as shown @@ -577,6 +581,38 @@ in the following example: NOTE: `@SpringBootApplication` also provides aliases to customize the attributes of `@EnableAutoConfiguration` and `@ComponentScan`. +[NOTE] +==== +None of these features are mandatory and you may chose to replace this single annotation +by any of the features that it enables. For instance, you may not want to use component +scan in your application: + +[source,java,indent=0] +---- + package com.example.myapplication; + + import org.springframework.boot.SpringApplication; + import org.springframework.context.annotation.ComponentScan + import org.springframework.context.annotation.Configuration; + import org.springframework.context.annotation.Import; + + @Configuration + @EnableAutoConfiguration + @Import({ MyConfig.class, MyAnotherConfig.class }) + public class Application { + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + + } +---- + +In this example, `Application` is just like any other Spring Boot application except that +`@Component`-annotated classes are not detected automatically and the user-defined beans +are imported explicitly (see `@Import`). +==== + [[using-boot-running-your-application]]