Harmonize references to application.yaml files in reference docs

See gh-34628
pull/35401/head
Ivan Dimitrov 2 years ago 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. 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>>. 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. 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`. 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. 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). . <<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. 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: 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]] [[features.external-config.files.profile-specific]]
==== Profile Specific Files ==== 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}`. 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. 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. 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]] [[features.external-config.files.property-placeholders]]
==== 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. 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}`. 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. Documents are processed in order, from top to bottom.
Later documents can override the properties defined in earlier ones. 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. Three consecutive hyphens represent the end of one document, and the start of the next.
For example, the following file has two logical documents: 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 | Property | Note
| `my.main-project.person.first-name` | `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` | `my.main-project.person.firstName`
| Standard camel case syntax. | Standard camel case syntax.
| `my.main-project.person.first_name` | `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` | `MY_MAINPROJECT_PERSON_FIRSTNAME`
| Upper case format, which is recommended when using system environment variables. | 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]] [[features.profiles.profile-specific-configuration-files]]
=== 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. 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]] [[howto.build.create-a-nonexecutable-jar]]
=== Create a Non-executable JAR with Exclusions === 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. 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: 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> <configuration>
<classifier>lib</classifier> <classifier>lib</classifier>
<excludes> <excludes>
<exclude>application.yml</exclude> <exclude>application.yaml</exclude>
</excludes> </excludes>
</configuration> </configuration>
</execution> </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. 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. 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`. 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 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`). 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. 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]] [[howto.properties-and-configuration.discover-build-in-options-for-external-properties]]
=== Discover Built-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. 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`. 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]] [[howto.webserver.configure-ssl]]
=== 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: The following example shows setting SSL properties using a Java KeyStore file:
[source,yaml,indent=0,subs="verbatim",configprops,configblocks] [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]] [[howto.webserver.configure]]
=== Configure the Web Server === 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>>`"). 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. 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>>. 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" 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. 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. See the https://docs.hazelcast.org/docs/latest/manual/html-single/[Hazelcast documentation] for more details.

Loading…
Cancel
Save