From ce6e1548fdeac3681e65a4f9c1de8566192ba409 Mon Sep 17 00:00:00 2001 From: halo Date: Wed, 10 Jun 2026 03:22:47 +0900 Subject: [PATCH 1/2] docs: add observability page to nav and fix heading level The observability.adoc page existed but was unreachable from the documentation navigation and would cause unresolved reference errors when building the release train docs. - Add `* xref:observability.adoc[]` to nav.adoc so the page appears in the sidebar - Promote the heading from level 2 (`==`) to level 1 (`=`) so it is valid as a standalone Antora page Fixes #2272 Co-Authored-By: Claude Sonnet 4.6 --- docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/observability.adoc | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 7d2eea9541..0172b46e56 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -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[] diff --git a/docs/modules/ROOT/pages/observability.adoc b/docs/modules/ROOT/pages/observability.adoc index a229031d68..8b5c5ddf21 100644 --- a/docs/modules/ROOT/pages/observability.adoc +++ b/docs/modules/ROOT/pages/observability.adoc @@ -1,5 +1,5 @@ [[observability]] -== Observability metadata += Observability include::partial$_metrics.adoc[] From 4c7db228926ef25f4391bba59c70432879c8deff Mon Sep 17 00:00:00 2001 From: halo Date: Wed, 10 Jun 2026 04:52:28 +0900 Subject: [PATCH 2/2] docs: document .json alternative format endpoint and add URL pattern table The serving-alternative-formats page documented .yml/.yaml/.properties suffixes but omitted the .json flat format endpoint. Add the missing suffix and a table summarising all six supported URL patterns (with and without a label segment), including the new .json variants. Closes #722 Co-Authored-By: Claude Sonnet 4.6 --- .../server/serving-alternative-formats.adoc | 35 ++++++++++++++++--- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/modules/ROOT/pages/server/serving-alternative-formats.adoc b/docs/modules/ROOT/pages/server/serving-alternative-formats.adoc index 27e4afdc9b..d04a7fb86a 100644 --- a/docs/modules/ROOT/pages/server/serving-alternative-formats.adoc +++ b/docs/modules/ROOT/pages/server/serving-alternative-formats.adoc @@ -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.