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
10 changes: 3 additions & 7 deletions docs/_static/api-reference/nuts-node-api.js
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,14 @@ 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()) {
const suffix = api.slug.replaceAll("-", "_");
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);
Expand All @@ -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;
}
Expand Down
19 changes: 19 additions & 0 deletions docs/_static/api-reference/scalar.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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}`;
Expand Down
Loading