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}`;