From f07365f059ff603ba4437655f992dc0d59cda7e6 Mon Sep 17 00:00:00 2001 From: JorisHeadease Date: Tue, 17 Nov 2026 17:25:02 +0100 Subject: [PATCH] docs(api): put APIs at menu root, clarify nesting (#4708) Backport of #4708 to V5.4, adapted because V5.4 has no deprecated APIs: dropping x-tagGroups moves the APIs from the single "APIs" group to the menu root, so no Deprecated tag and no breadcrumb rule are needed. Custom CSS gives nested objects and expanded responses a stronger line and a tint per level, as on master. --- docs/_static/api-reference/nuts-node-api.js | 10 +++------- docs/_static/api-reference/scalar.js | 19 +++++++++++++++++++ 2 files changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/_static/api-reference/nuts-node-api.js b/docs/_static/api-reference/nuts-node-api.js index 45e59076d..4bb2ce53b 100644 --- a/docs/_static/api-reference/nuts-node-api.js +++ b/docs/_static/api-reference/nuts-node-api.js @@ -35,7 +35,6 @@ export async function loadNutsNodeApi() { components: {schemas: {...sharedTypes.components.schemas}, responses: {ErrorResponse: paste(errorResponse, {}, "", url("common/error_response.yaml"))}}, tags: [], }; - const groups = {APIs: [], Deprecated: []}; const introductions = {APIs: [], Deprecated: []}; const operationIds = new Set(); for (const [index, api] of apis.entries()) { @@ -43,8 +42,7 @@ export async function loadNutsNodeApi() { const spec = paste(specs[index], combined.components, suffix, url(api.file)); // Tag names include the API name: that keeps them unique when two APIs use the same tag, and readable in - // tools that ignore x-tagGroups, like Postman. The menu has one level of groups, so it shows an API as one - // tag, or as one tag per tag of the API. + // tools that show the tags as a flat list. The menu shows an API as one tag, or as one tag per tag of the API. const operations = Object.values(spec.paths).flatMap((item) => methods.map((method) => item[method]).filter(Boolean)); // The menu only shows tagged operations; an operation without tags has to get one in its spec. const untagged = operations.find((operation) => !operation.tags?.length); @@ -68,14 +66,12 @@ export async function loadNutsNodeApi() { combined.paths[path] = item; } const group = api.deprecated ? "Deprecated" : "APIs"; - groups[group].push(...names.map(tag)); const summary = spec.info.description?.trim().replace(/\s+/g, " "); introductions[group].push(`- **${api.name}** ([${api.file}](${url(api.file)}))` + (summary ? `: ${summary}` : "")); combined.info.license ??= spec.info.license; } - // A heading without APIs, like Deprecated in v5.4, is left out. - combined["x-tagGroups"] = Object.entries(groups).filter(([, tags]) => tags.length).map(([name, tags]) => ({name, tags})); - // Lists instead of headings, which renderers would add to the menu. They link each API's own spec. + // Lists instead of headings, which renderers would add to the menu. They link each API's own spec. A list without + // APIs, like Deprecated in v5.4, is left out. combined.info.description = Object.entries(introductions).filter(([, lines]) => lines.length).map(([group, lines]) => `**${group}**\n\n${lines.join("\n")}`).join("\n\n"); return combined; } diff --git a/docs/_static/api-reference/scalar.js b/docs/_static/api-reference/scalar.js index c93532fc8..e1cdced7d 100644 --- a/docs/_static/api-reference/scalar.js +++ b/docs/_static/api-reference/scalar.js @@ -19,6 +19,22 @@ const scripts = [ }, ]; +// Uses Scalar's own class names and variables, so check the result when upgrading Scalar. +const customCss = ` +/* Scalar draws nesting in schemas with a faint line only. A stronger line and a tint for each nested object and + expanded response show where it starts and ends. The tints add up, so deeper levels get a stronger tint. + A collapsed panel can stay in the page as hidden="until-found", for find in page; it gets no tint or padding. */ +.scalar-app { --schema-rail-base: var(--scalar-color-3); } +.scalar-app .schema-rail { border-inline-start-width: 2px; } +.scalar-app .schema-rail-panel.property-children:not([hidden]), +.scalar-app .responses-list--tree .schema-rail-panel.parameter-item-container:not([hidden]) { + background: color-mix(in srgb, var(--scalar-background-2) 70%, transparent); + border-radius: 0 var(--scalar-radius-lg) var(--scalar-radius-lg) 0; + padding-block: 2px; + padding-inline-end: 12px; +} +`; + export async function renderNutsApiReference(selector) { const element = document.querySelector(selector); try { @@ -31,6 +47,9 @@ export async function renderNutsApiReference(selector) { // The client button opens Scalar's hosted client with the URL of this page, which cannot load the // document combined here. The Test Request buttons work. hideClientButton: true, + // Keeps all APIs in view; Scalar opens the first menu item otherwise. + defaultOpenFirstTag: false, + customCss, }); } catch (error) { element.textContent = `The API reference could not be loaded: ${error.message}`;