From d041c7d6b9a3ac1ea079e4f3ca0225fa9e6c3afc Mon Sep 17 00:00:00 2001
From: Madhura Bhave <mbhave@pivotal.io>
Date: Thu, 3 Dec 2020 12:17:53 -0800
Subject: [PATCH] Document the granularity for property document imports

Closes gh-22987
---
 .../docs/asciidoc/spring-boot-features.adoc   | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
index ee58a3aae4..7f8cd14676 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
@@ -711,7 +711,7 @@ If you've already directly <<boot-features-external-config-files-importing,impor
 [[boot-features-external-config-files-importing]]
 ==== Importing Additional Data
 Application properties may import further config data from other locations using the `spring.config.import` property.
-Imports are processed as they are discovered, and are treated as an additional documents inserted immediately below the one that declares the import.
+Imports are processed as they are discovered, and are treated as additional documents inserted immediately below the one that declares the import.
 
 For example, you might have the following in your classpath `application.properties` file:
 
@@ -727,6 +727,23 @@ For example, you might have the following in your classpath `application.propert
 This will trigger the import of a `dev.properties` file in current directory (if such a file exists).
 Values from the imported `dev.properties` will take precedence over the file that triggered the import.
 In the above example, the `dev.properties` could redefine `spring.application.name` to a different value.
+An import will only be imported once no matter how many times it is declared.
+The order an import is defined inside a single document within the properties/yaml file doesn't matter.
+For instance, the two examples below produce the same result:
+
+[source,yaml,indent=0,configblocks]
+----
+spring.config.import=my.properties
+my.property=value
+----
+
+[source,yaml,indent=0,configblocks]
+----
+my.property=value
+spring.config.import=my.properties
+----
+
+In both of the above examples, the values from the `my.properties` file will take precedence over the file that triggered its import.
 
 Several locations can be specified under a single `spring.config.import` key.
 Locations will be processed in the order that they are defined, with later imports taking precedence.