From 34dee77a3ec4d688f6b3d78b51cf2c690d8c4e1f Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Wed, 14 May 2025 16:20:35 -0700 Subject: [PATCH] Improve "profile" reference documentation with additional admonitions Closes gh-45522 --- .../reference/pages/features/external-config.adoc | 2 ++ .../reference/pages/features/profiles.adoc | 15 +++++++++++---- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/external-config.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/external-config.adoc index d7e2bb024bb..671c62da78d 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/external-config.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/external-config.adoc @@ -8,6 +8,8 @@ Property values can be injected directly into your beans by using the javadoc:or Spring Boot uses a very particular javadoc:org.springframework.core.env.PropertySource[] order that is designed to allow sensible overriding of values. Later property sources can override the values defined in earlier ones. + +[[features.external-config.order]] Sources are considered in the following order: . Default properties (specified by setting javadoc:org.springframework.boot.SpringApplication#setDefaultProperties(java.util.Map)[]). diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/profiles.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/profiles.adoc index c720b557bf5..885502f3be9 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/profiles.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/profiles.adoc @@ -53,16 +53,19 @@ spring: active: "metrics" ---- +The configprop:spring.profiles.active[] property follows the same ordering rules as other properties. +The highest javadoc:org.springframework.core.env.PropertySource[] wins. +This means that you can specify active profiles in `application.properties` and then *replace* them by using the command line switch. + +TIP: See xref:features/external-config.adoc#features.external-config.order[the "`Externalized Configuration`"] for more details on the order in which property sources are considered. + [[features.profiles.adding-active-profiles]] == Adding Active Profiles -The configprop:spring.profiles.active[] property follows the same ordering rules as other properties: The highest javadoc:org.springframework.core.env.PropertySource[] wins. -This means that you can specify active profiles in `application.properties` and then *replace* them by using the command line switch. - Sometimes, it is useful to have properties that *add* to the active profiles rather than replace them. -The `spring.profiles.include` property can be used to add active profiles on top of those activated by the configprop:spring.profiles.active[] property. +The configprop:spring.profiles.include[] property can be used to add active profiles on top of those activated by the configprop:spring.profiles.active[] property. The javadoc:org.springframework.boot.SpringApplication[] entry point also has a Java API for setting additional profiles. See the `setAdditionalProfiles()` method in javadoc:org.springframework.boot.SpringApplication[]. @@ -77,6 +80,10 @@ spring: - "local" ---- +NOTE: Included profiles are added before any configprop:spring.profiles.active[] profiles. + +TIP: The configprop:spring.profiles.include[] property is processed for each property source, as such the usual xref:features/external-config.adoc#features.external-config.typesafe-configuration-properties.merging-complex-types[complex type merging rules] for lists do not apply. + WARNING: Similar to `spring.profiles.active`, `spring.profiles.include` can only be used in non-profile-specific documents. This means it cannot be included in xref:features/external-config.adoc#features.external-config.files.profile-specific[profile specific files] or xref:features/external-config.adoc#features.external-config.files.activation-properties[documents activated] by `spring.config.activate.on-profile`.