root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 12 Packages Projects Releases Wiki Activity

Merge branch '2.1.x' 

Closes gh-17603
This commit is contained in:
Stephane Nicoll 2019-07-22 15:29:58 +02:00
parent c82e33e1d7 30fe10613d
commit a1f32bbd7a
1 changed files with 43 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View File

@ -8733,16 +8733,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
<<appendix.adoc#configuration-metadata-annotation-processor,trigger meta-data
generation>> 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.
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.