From b3a46fc50e9e0f08cd5d98e90941afc0e462f394 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Mon, 13 Jun 2022 18:18:23 -0700 Subject: [PATCH] Document that placeholders should us the canonical property name form Closes gh-31309 --- .../docs/asciidoc/features/external-config.adoc | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/external-config.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/external-config.adoc index 3d38486405c4..010825d00933 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/external-config.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/external-config.adoc @@ -458,6 +458,15 @@ The use of placeholders with and without defaults is shown in the following exam Assuming that the `username` property has not been set elsewhere, `app.description` will have the value `MyApp is a Spring Boot application written by Unknown`. +[NOTE] +==== +You should always refer to property names in the placeholder using their canonical form (kebab-case using only lowercase letters). +This will allow Spring Boot to use the same logic as it does when <> `@ConfigurationProperties`. + +For example, `${demo.item-price}` will pick up `demo.item-price` and `demo.itemPrice` forms from the `application.properties` file, as well as `DEMO_ITEMPRICE` from the system environment. +If you used `${demo.itemPrice}` instead, `demo.item-price` and `DEMO_ITEMPRICE` would not be considered. +==== + TIP: You can also use this technique to create "`short`" variants of existing Spring Boot properties. See the _<>_ how-to for details. @@ -1222,10 +1231,14 @@ The following table summarizes the features that are supported by `@Configuratio |=== [[features.external-config.typesafe-configuration-properties.vs-value-annotation.note]] -NOTE: If you do want to use `@Value`, we recommend that you refer to property names using their canonical form (kebab-case using only lowercase letters). -This will allow Spring Boot to use the same logic as it does when relaxed binding `@ConfigurationProperties`. +[NOTE] +==== +If you do want to use `@Value`, we recommend that you refer to property names using their canonical form (kebab-case using only lowercase letters). +This will allow Spring Boot to use the same logic as it does when <> `@ConfigurationProperties`. + For example, `@Value("{demo.item-price}")` will pick up `demo.item-price` and `demo.itemPrice` forms from the `application.properties` file, as well as `DEMO_ITEMPRICE` from the system environment. If you used `@Value("{demo.itemPrice}")` instead, `demo.item-price` and `DEMO_ITEMPRICE` would not be considered. +==== If you define a set of configuration keys for your own components, we recommend you group them in a POJO annotated with `@ConfigurationProperties`. Doing so will provide you with structured, type-safe object that you can inject into your own beans.