From 300f07b2a8aa5d2792f084b5e8b06e41912088bb Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Mon, 22 Jul 2019 15:20:37 +0200 Subject: [PATCH 1/2] Polish --- .../src/main/asciidoc/appendix-application-properties.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc index 75f0468263..6dc8d0ef16 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc @@ -546,7 +546,7 @@ content into your application. Rather, pick only the properties that you need. # SECURITY OAUTH2 RESOURCE SERVER ({sc-spring-boot-autoconfigure}/security/oauth2/resource/OAuth2ResourceServerProperties.{sc-ext}[OAuth2ResourceServerProperties]) spring.security.oauth2.resourceserver.jwt.jwk-set-uri= # JSON Web Key URI to use to verify the JWT token. - spring.security.oauth2.resourceserver.jwt.issuer-uri= # URI that an OpenID Connect Provider asserts as its Issuer Identifier. + spring.security.oauth2.resourceserver.jwt.issuer-uri= # URI that an OpenID Connect Provider asserts as its Issuer Identifier. # ---------------------------------------- # DATA PROPERTIES From 30fe10613def6d9d7e54cd6e0ef9dbf3d7763732 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Mon, 22 Jul 2019 15:28:17 +0200 Subject: [PATCH 2/2] Improve how to configure configuration keys of a custom starter Closes gh-17573 --- .../main/asciidoc/spring-boot-features.adoc | 47 +++++++++++++++++-- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index f538ebe827..938b5cf74b 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -8403,16 +8403,55 @@ assume that you are creating a starter for "acme" and that you name the auto-con module `acme-spring-boot-autoconfigure` and the starter `acme-spring-boot-starter`. If you only have one module that combines the two, name it `acme-spring-boot-starter`. -Also, if your starter provides configuration keys, use a unique namespace for them. In + + +[[boot-features-custom-starter-configuration-keys]] +==== Configuration keys +If your starter provides configuration keys, use a unique namespace for them. In particular, do not include your keys in the namespaces that Spring Boot uses (such as `server`, `management`, `spring`, and so on). If you use the same namespace, we may modify -these namespaces in the future in ways that break your modules. +these namespaces in the future in ways that break your modules. As a rule of thumb, +prefix all your keys with a namespace that you own (e.g. `acme`). + +Make sure that configuration keys are documented by adding field javadoc for each +property, as shown in the following example: + +[source,java,indent=0] +---- + @ConfigurationProperties("acme") + public class AcmeProperties { + + /** + * Whether to check the location of acme resources. + */ + private boolean checkLocation = true; + + /** + * Timeout for establishing a connection to the acme server. + */ + private Duration loginTimeout = Duration.ofSeconds(3); + + // getters & setters + + } +---- + +Here are some rules we follow internally to make sure descriptions are consistent: + +* Do not start the description by "The" or "A". +* For `boolean` types, start the description with "Whether" or "Enable". +* For collection-based types, start the description with "Comma-separated list" +* Use `java.time.Duration` rather than `long` and describe the default unit if it differs +from milliseconds, e.g. "If a duration suffix is not specified, seconds will be used". +* Do not provide the default value in the description unless it has to be determined at +runtime. Make sure to <> so that IDE assistance is available for your keys as well. You may -want to review the generated meta-data (`META-INF/spring-configuration-metadata.json`) to -make sure your keys are properly documented. +want to review the generated metadata (`META-INF/spring-configuration-metadata.json`) to +make sure your keys are properly documented. Using your own starter in a compatible IDE is +also a good idea to validate that quality of the metadata.