Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,4 @@
** xref:server/push-notifications-and-bus.adoc[]
** xref:server/aot-and-native-image-support.adoc[]
* xref:client.adoc[]
* xref:observability.adoc[]
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/observability.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[[observability]]
== Observability metadata
= Observability

include::partial$_metrics.adoc[]

Expand Down
35 changes: 30 additions & 5 deletions docs/modules/ROOT/pages/server/serving-alternative-formats.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,39 @@
:page-section-summary-toc: 1

The default JSON format from the environment endpoints is perfect for consumption by Spring applications, because it maps directly onto the `Environment` abstraction.
If you prefer, you can consume the same data as YAML or Java properties by adding a suffix (".yml", ".yaml" or ".properties") to the resource path.
If you prefer, you can consume the same data as a flat JSON object, YAML, or Java properties by adding a suffix (`.json`, `.yml`, `.yaml`, or `.properties`) to the resource path.
This can be useful for consumption by applications that do not care about the structure of the JSON endpoints or the extra metadata they provide (for example, an application that is not using Spring might benefit from the simplicity of this approach).

The YAML and properties representations have an additional flag (provided as a boolean query parameter called `resolvePlaceholders`) to signal that placeholders in the source documents (in the standard Spring `${...}` form) should be resolved in the output before rendering, where possible.
The following URL patterns are supported:

[cols="2,3", options="header"]
|===
| URL pattern | Description

| `/{application}-{profile}.json`
| Flat JSON object (coalesced from all property sources)

| `/{label}/{application}-{profile}.json`
| Same, at a specific label (branch, tag, or commit)

| `/{application}-{profile}.yml` (or `.yaml`)
| Flat YAML representation

| `/{label}/{application}-{profile}.yml` (or `.yaml`)
| Same, at a specific label

| `/{application}-{profile}.properties`
| Java `.properties` format

| `/{label}/{application}-{profile}.properties`
| Same, at a specific label
|===

The flat JSON, YAML, and properties representations have an additional flag (provided as a boolean query parameter called `resolvePlaceholders`) to signal that placeholders in the source documents (in the standard Spring `${...}` form) should be resolved in the output before rendering, where possible.
This is a useful feature for consumers that do not know about the Spring placeholder conventions.

NOTE: There are limitations in using the YAML or properties formats, mainly in relation to the loss of metadata.
For example, the JSON is structured as an ordered list of property sources, with names that correlate with the source.
The YAML and properties forms are coalesced into a single map, even if the origin of the values has multiple sources, and the names of the original source files are lost.
NOTE: There are limitations in using these flat formats, mainly in relation to the loss of metadata.
For example, the full JSON environment representation is structured as an ordered list of property sources, with names that correlate with the source.
The flat JSON, YAML, and properties forms are coalesced into a single map, even if the origin of the values has multiple sources, and the names of the original source files are lost.
Also, the YAML representation is not necessarily a faithful representation of the YAML source in a backing repository either. It is constructed from a list of flat property sources, and assumptions have to be made about the form of the keys.