Harmonize references to application.yaml files in reference docs
See gh-34628
This commit is contained in:
committed by
Stephane Nicoll
parent
81ade5d3b5
commit
f4db73ead9
@@ -5,7 +5,7 @@ include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
|
||||
Various properties can be specified inside your `application.properties` file, inside your `application.yaml` file, or as command line switches.
|
||||
This appendix provides a list of common Spring Boot properties and references to the underlying classes that consume them.
|
||||
|
||||
TIP: Spring Boot provides various conversion mechanism with advanced value formatting, make sure to review <<features#features.external-config.typesafe-configuration-properties.conversion, the properties conversion section>>.
|
||||
|
||||
@@ -6,7 +6,7 @@ include::attributes.adoc[]
|
||||
|
||||
|
||||
Spring Boot jars include metadata files that provide details of all supported configuration properties.
|
||||
The files are designed to let IDE developers offer contextual help and "`code completion`" as users are working with `application.properties` or `application.yml` files.
|
||||
The files are designed to let IDE developers offer contextual help and "`code completion`" as users are working with `application.properties` or `application.yaml` files.
|
||||
|
||||
The majority of the metadata file is generated automatically at compile time by processing all items annotated with `@ConfigurationProperties`.
|
||||
However, it is possible to <<configuration-metadata#appendix.configuration-metadata.annotation-processor.adding-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
|
||||
|
||||
@@ -35,7 +35,7 @@ Config data files are considered in the following order:
|
||||
. <<features#features.external-config.files.profile-specific,Profile-specific application properties>> outside of your packaged jar (`application-\{profile}.properties` and YAML variants).
|
||||
|
||||
NOTE: It is recommended to stick with one format for your entire application.
|
||||
If you have configuration files with both `.properties` and `.yml` format in the same location, `.properties` takes precedence.
|
||||
If you have configuration files with both `.properties` and YAML format in the same location, `.properties` takes precedence.
|
||||
|
||||
To provide a concrete example, suppose you develop a `@Component` that uses a `name` property, as shown in the following example:
|
||||
|
||||
@@ -220,7 +220,7 @@ You cannot use a wildcard in a `classpath:` location.
|
||||
[[features.external-config.files.profile-specific]]
|
||||
==== Profile Specific Files
|
||||
As well as `application` property files, Spring Boot will also attempt to load profile-specific files using the naming convention `application-\{profile}`.
|
||||
For example, if your application activates a profile named `prod` and uses YAML files, then both `application.yml` and `application-prod.yml` will be considered.
|
||||
For example, if your application activates a profile named `prod` and uses YAML files, then both `application.yaml` and `application-prod.yaml` will be considered.
|
||||
|
||||
Profile-specific properties are loaded from the same locations as standard `application.properties`, with profile-specific files always overriding the non-specific ones.
|
||||
If several profiles are specified, a last-wins strategy applies.
|
||||
@@ -441,7 +441,7 @@ For example, if a secret named `db.password` is mounted at location `/run/secret
|
||||
|
||||
[[features.external-config.files.property-placeholders]]
|
||||
==== Property Placeholders
|
||||
The values in `application.properties` and `application.yml` are filtered through the existing `Environment` when they are used, so you can refer back to previously defined values (for example, from System properties or environment variables).
|
||||
The values in `application.properties` and `application.yaml` are filtered through the existing `Environment` when they are used, so you can refer back to previously defined values (for example, from System properties or environment variables).
|
||||
The standard `$\{name}` property-placeholder syntax can be used anywhere within a value.
|
||||
Property placeholders can also specify a default value using a `:` to separate the default value from the property name, for example `${name:default}`.
|
||||
|
||||
@@ -476,7 +476,7 @@ Spring Boot allows you to split a single physical file into multiple logical doc
|
||||
Documents are processed in order, from top to bottom.
|
||||
Later documents can override the properties defined in earlier ones.
|
||||
|
||||
For `application.yml` files, the standard YAML multi-document syntax is used.
|
||||
For `application.yaml` files, the standard YAML multi-document syntax is used.
|
||||
Three consecutive hyphens represent the end of one document, and the start of the next.
|
||||
|
||||
For example, the following file has two logical documents:
|
||||
@@ -834,13 +834,13 @@ With the preceding code, the following properties names can all be used:
|
||||
| Property | Note
|
||||
|
||||
| `my.main-project.person.first-name`
|
||||
| Kebab case, which is recommended for use in `.properties` and `.yml` files.
|
||||
| Kebab case, which is recommended for use in `.properties` and YAML files.
|
||||
|
||||
| `my.main-project.person.firstName`
|
||||
| Standard camel case syntax.
|
||||
|
||||
| `my.main-project.person.first_name`
|
||||
| Underscore notation, which is an alternative format for use in `.properties` and `.yml` files.
|
||||
| Underscore notation, which is an alternative format for use in `.properties` and YAML files.
|
||||
|
||||
| `MY_MAINPROJECT_PERSON_FIRSTNAME`
|
||||
| Upper case format, which is recommended when using system environment variables.
|
||||
|
||||
@@ -115,5 +115,5 @@ It is also possible to activate profiles by using Spring's `ConfigurableEnvironm
|
||||
|
||||
[[features.profiles.profile-specific-configuration-files]]
|
||||
=== Profile-specific Configuration Files
|
||||
Profile-specific variants of both `application.properties` (or `application.yml`) and files referenced through `@ConfigurationProperties` are considered as files and loaded.
|
||||
Profile-specific variants of both `application.properties` (or `application.yaml`) and files referenced through `@ConfigurationProperties` are considered as files and loaded.
|
||||
See "<<features#features.external-config.files.profile-specific>>" for details.
|
||||
|
||||
@@ -212,7 +212,7 @@ For example, to indicate that JRuby should be flagged for unpacking by using the
|
||||
[[howto.build.create-a-nonexecutable-jar]]
|
||||
=== Create a Non-executable JAR with Exclusions
|
||||
Often, if you have an executable and a non-executable jar as two separate build products, the executable version has additional configuration files that are not needed in a library jar.
|
||||
For example, the `application.yml` configuration file might be excluded from the non-executable JAR.
|
||||
For example, the `application.yaml` configuration file might be excluded from the non-executable JAR.
|
||||
|
||||
In Maven, the executable jar must be the main artifact and you can add a classified jar for the library, as follows:
|
||||
|
||||
@@ -236,7 +236,7 @@ In Maven, the executable jar must be the main artifact and you can add a classif
|
||||
<configuration>
|
||||
<classifier>lib</classifier>
|
||||
<excludes>
|
||||
<exclude>application.yml</exclude>
|
||||
<exclude>application.yaml</exclude>
|
||||
</excludes>
|
||||
</configuration>
|
||||
</execution>
|
||||
|
||||
@@ -146,7 +146,7 @@ You can also provide the following System properties (or environment variables)
|
||||
A separate `Environment` property source is set up for this document and it can be overridden by system properties, environment variables, or the command line.
|
||||
|
||||
No matter what you set in the environment, Spring Boot always loads `application.properties` as described above.
|
||||
By default, if YAML is used, then files with the '`.yml`' extension are also added to the list.
|
||||
By default, if YAML is used, then files with the '`.yaml`' and '`.yml`' extension are also added to the list.
|
||||
|
||||
TIP: If you want detailed information about the files that are being loaded you can <<features#features.logging.log-levels, set the logging level>> of `org.springframework.boot.context.config` to `trace`.
|
||||
|
||||
@@ -187,7 +187,7 @@ YAML is a superset of JSON and, as such, is a convenient syntax for storing exte
|
||||
port: 9000
|
||||
----
|
||||
|
||||
Create a file called `application.yml` and put it in the root of your classpath.
|
||||
Create a file called `application.yaml` and put it in the root of your classpath.
|
||||
Then add `snakeyaml` to your dependencies (Maven coordinates `org.yaml:snakeyaml`, already included if you use the `spring-boot-starter`).
|
||||
A YAML file is parsed to a Java `Map<String,Object>` (like a JSON object), and Spring Boot flattens the map so that it is one level deep and has period-separated keys, as many people are used to with `Properties` files in Java.
|
||||
|
||||
@@ -287,7 +287,7 @@ Later values override earlier values.
|
||||
|
||||
[[howto.properties-and-configuration.discover-build-in-options-for-external-properties]]
|
||||
=== Discover Built-in Options for External Properties
|
||||
Spring Boot binds external properties from `application.properties` (or `.yml` files and other places) into an application at runtime.
|
||||
Spring Boot binds external properties from `application.properties` (or YAML files and other places) into an application at runtime.
|
||||
There is not (and technically cannot be) an exhaustive list of all supported properties in a single location, because contributions can come from additional jar files on your classpath.
|
||||
|
||||
A running application with the Actuator features has a `configprops` endpoint that shows all the bound and bindable properties available through `@ConfigurationProperties`.
|
||||
|
||||
@@ -182,7 +182,7 @@ You can configure this behavior by setting the configprop:server.compression.mim
|
||||
|
||||
[[howto.webserver.configure-ssl]]
|
||||
=== Configure SSL
|
||||
SSL can be configured declaratively by setting the various `+server.ssl.*+` properties, typically in `application.properties` or `application.yml`.
|
||||
SSL can be configured declaratively by setting the various `+server.ssl.*+` properties, typically in `application.properties` or `application.yaml`.
|
||||
The following example shows setting SSL properties using a Java KeyStore file:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
@@ -280,7 +280,7 @@ As of Undertow 1.4.0+, both `h2` and `h2c` are supported on JDK 8 without any ad
|
||||
|
||||
[[howto.webserver.configure]]
|
||||
=== Configure the Web Server
|
||||
Generally, you should first consider using one of the many available configuration keys and customize your web server by adding new entries in your `application.properties` or `application.yml` file.
|
||||
Generally, you should first consider using one of the many available configuration keys and customize your web server by adding new entries in your `application.properties` or `application.yaml` file.
|
||||
See "`<<howto#howto.properties-and-configuration.discover-build-in-options-for-external-properties>>`").
|
||||
The `server.{asterisk}` namespace is quite useful here, and it includes namespaces like `server.tomcat.{asterisk}`, `server.jetty.{asterisk}` and others, for server-specific features.
|
||||
See the list of <<application-properties#appendix.application-properties>>.
|
||||
|
||||
@@ -26,7 +26,7 @@ You could also specify the Hazelcast configuration file to use through configura
|
||||
config: "classpath:config/my-hazelcast.xml"
|
||||
----
|
||||
|
||||
Otherwise, Spring Boot tries to find the Hazelcast configuration from the default locations: `hazelcast.xml` in the working directory or at the root of the classpath, or a `.yaml`/`.yml` counterpart in the same locations.
|
||||
Otherwise, Spring Boot tries to find the Hazelcast configuration from the default locations: `hazelcast.xml` in the working directory or at the root of the classpath, or a YAML counterpart in the same locations.
|
||||
We also check if the `hazelcast.config` system property is set.
|
||||
See the https://docs.hazelcast.org/docs/latest/manual/html-single/[Hazelcast documentation] for more details.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user