From 672e585bde0aeaf2f006e6e0458e03645f3232d5 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) Addresses the feedback on nuts-foundation/nuts-knooppunt#651. The deprecated APIs nest under a Deprecated tag through the OpenAPI 3.2 tag parent instead of x-tagGroups, so the other APIs sit at the menu root. Custom CSS gives nested objects and expanded responses a stronger line and a tint per level, and hides Scalar's breadcrumb bar, which shows an unrelated trail outside the deprecated APIs once a tag has a parent. --- docs/_static/api-reference/nuts-node-api.js | 15 +++++++------- docs/_static/api-reference/scalar.js | 22 +++++++++++++++++++++ 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/_static/api-reference/nuts-node-api.js b/docs/_static/api-reference/nuts-node-api.js index 4be180e57..71f625f61 100644 --- a/docs/_static/api-reference/nuts-node-api.js +++ b/docs/_static/api-reference/nuts-node-api.js @@ -2,8 +2,8 @@ // This runs in the browser, so building the docs needs no extra tools and no generated spec is committed. // It parses YAML with the global jsyaml, which scalar.js loads. -// In menu order, under two headings: APIs and Deprecated. The names say DEPRECATED as well, for tools that -// ignore the headings (x-tagGroups), like Postman. +// In menu order. The deprecated APIs go under a Deprecated item at the end of the menu. Their names say DEPRECATED +// as well, for tools that show the tags as a flat list. const apis = [ {file: "auth/v2.yaml", name: "Auth (v2)", slug: "auth-v2"}, {file: "crypto/v1.yaml", name: "Crypto", slug: "crypto"}, @@ -39,7 +39,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()) { @@ -47,8 +46,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 ("auth" is in two APIs) 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. + // 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); @@ -57,7 +55,8 @@ export async function loadNutsNodeApi() { const tag = (name) => names.length === 1 ? api.name : `${api.name}: ${name}`; for (const name of names) { const description = spec.tags?.find((declared) => declared.name === name)?.description; - combined.tags.push({name: tag(name), ...(description && {description})}); + // parent comes from OpenAPI 3.2; Scalar nests by it in this 3.0 document too. + combined.tags.push({name: tag(name), ...(api.deprecated && {parent: "Deprecated"}), ...(description && {description})}); } // Each operation gets the servers and security of its own spec. Scalar ignores servers on a path. for (const operation of operations) { @@ -72,12 +71,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; } - combined["x-tagGroups"] = Object.entries(groups).map(([name, tags]) => ({name, tags})); + // The parent of the deprecated APIs' tags. The menu follows the order of this list, so it comes last. + combined.tags.push({name: "Deprecated"}); // Lists instead of headings, which renderers would add to the menu. They link each API's own spec. combined.info.description = Object.entries(introductions).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..3dc0932d2 100644 --- a/docs/_static/api-reference/scalar.js +++ b/docs/_static/api-reference/scalar.js @@ -19,6 +19,25 @@ 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; +} +/* Scalar shows this breadcrumb bar once a tag has a parent, like the deprecated APIs have. Outside those APIs it + shows the first nested tag of the document instead of the section in view. */ +.scalar-app .context-bar { display: none; } +`; + export async function renderNutsApiReference(selector) { const element = document.querySelector(selector); try { @@ -31,6 +50,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}`;