diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/developing-auto-configuration.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/developing-auto-configuration.adoc index 7ba8f3912d0d..f361c55f215f 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/developing-auto-configuration.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/developing-auto-configuration.adoc @@ -6,19 +6,17 @@ Auto-configuration classes can be bundled in external jars and still be picked-u Auto-configuration can be associated to a "`starter`" that provides the auto-configuration code as well as the typical libraries that you would use with it. We first cover what you need to know to build your own auto-configuration and then we move on to the <>. -TIP: A https://github.com/snicoll-demos/spring-boot-master-auto-configuration[demo project] is available to showcase how you can create a starter step-by-step. - [[features.developing-auto-configuration.understanding-auto-configured-beans]] === Understanding Auto-configured Beans -Under the hood, auto-configuration is implemented with the `@AutoConfiguration` annotation. +Classes that implement auto-configuration are annotated with `@AutoConfiguration`. This annotation itself is meta-annotated with `@Configuration`, making auto-configurations standard `@Configuration` classes. Additional `@Conditional` annotations are used to constrain when the auto-configuration should apply. Usually, auto-configuration classes use `@ConditionalOnClass` and `@ConditionalOnMissingBean` annotations. This ensures that auto-configuration applies only when relevant classes are found and when you have not declared your own `@Configuration`. -You can browse the source code of {spring-boot-autoconfigure-module-code}[`spring-boot-autoconfigure`] to see the `@Configuration` classes that Spring provides (see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports[`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`] file). +You can browse the source code of {spring-boot-autoconfigure-module-code}[`spring-boot-autoconfigure`] to see the `@AutoConfiguration` classes that Spring provides (see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports[`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`] file). @@ -26,7 +24,7 @@ You can browse the source code of {spring-boot-autoconfigure-module-code}[`sprin === Locating Auto-configuration Candidates Spring Boot checks for the presence of a `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` file within your published jar. -The file should list your configuration classes, as shown in the following example: +The file should list your configuration classes, with one class name per line, as shown in the following example: [indent=0] ---- @@ -34,18 +32,16 @@ The file should list your configuration classes, as shown in the following examp com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration ---- -TIP: You can use comments via `#` in this file. +TIP: You can add comments to the imports file using the `#` character. -NOTE: Auto-configurations must be loaded that way _only_. +NOTE: Auto-configurations must be loaded _only_ by being named in the imports file. Make sure that they are defined in a specific package space and that they are never the target of component scanning. Furthermore, auto-configuration classes should not enable component scanning to find additional components. Specific ``@Import``s should be used instead. -You can use the {spring-boot-autoconfigure-module-code}/AutoConfigureAfter.java[`@AutoConfigureAfter`] or {spring-boot-autoconfigure-module-code}/AutoConfigureBefore.java[`@AutoConfigureBefore`] annotations if your configuration needs to be applied in a specific order. +If your configuration needs to be applied in a specific order, you can use the `before`, `beforeName`, `after` and `afterName` attributes on the {spring-boot-autoconfigure-module-code}/AutoConfiguration.java[`@AutoConfiguration`] annotation or the dedicated {spring-boot-autoconfigure-module-code}/AutoConfigureBefore.java[`@AutoConfigureBefore`] and {spring-boot-autoconfigure-module-code}/AutoConfigureAfter.java[`@AutoConfigureAfter`] annotations. For example, if you provide web-specific configuration, your class may need to be applied after `WebMvcAutoConfiguration`. -TIP: If you are using the {spring-boot-autoconfigure-module-code}/AutoConfiguration.java[`@AutoConfiguration`] annotation, you can use the `before`, `beforeName`, `after` and `afterName` attribute aliases instead of the dedicated annotations. - If you want to order certain auto-configurations that should not have any direct knowledge of each other, you can also use `@AutoConfigureOrder`. That annotation has the same semantic as the regular `@Order` annotation but provides a dedicated order for auto-configuration classes. @@ -264,7 +260,8 @@ If you do it that way, the library is not provided and, by default, Spring Boot Spring Boot uses an annotation processor to collect the conditions on auto-configurations in a metadata file (`META-INF/spring-autoconfigure-metadata.properties`). If that file is present, it is used to eagerly filter auto-configurations that do not match, which will improve startup time. -It is recommended to add the following dependency in a module that contains auto-configurations: + +When building with Maven, it is recommended to add the following dependency in a module that contains auto-configurations: [source,xml,indent=0,subs="verbatim"] ---- @@ -299,16 +296,7 @@ If you have defined auto-configurations directly in your application, make sure ---- -With Gradle 4.5 and earlier, the dependency should be declared in the `compileOnly` configuration, as shown in the following example: - -[source,gradle,indent=0,subs="verbatim"] ----- - dependencies { - compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor" - } ----- - -With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example: +With Gradle, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example: [source,gradle,indent=0,subs="verbatim"] ----