feat(docs/ensnode.io): Add API Reference #1805
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,93 @@ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
notrab marked this conversation as resolved.
Outdated
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| <starlight-toc data-min-h="2" data-max-h="3"> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| <nav aria-labelledby="scalar__on-this-page"> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| <h2 id="scalar__on-this-page">On this page</h2> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| <ul class="scalar-toc-list"></ul> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| </nav> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| </starlight-toc> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| <script> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| function buildToc() { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const list = document.querySelector('.scalar-toc-list'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| if (!list) return; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const headings = document.querySelectorAll('h2.section-header-label[id]'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| if (headings.length === 0) return false; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list.innerHTML = ''; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| headings.forEach((h2) => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const li = document.createElement('li'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const a = document.createElement('a'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| a.href = `#${h2.id}`; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const span = document.createElement('span'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| span.textContent = h2.textContent?.trim() ?? ''; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| a.appendChild(span); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| li.appendChild(a); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| // Find h3s that belong to this h2's section | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const section = h2.closest('.section'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| if (section) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const h3s = section.querySelectorAll('h3[id]'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| if (h3s.length > 0) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const subList = document.createElement('ul'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| h3s.forEach((h3) => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const subLi = document.createElement('li'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const subA = document.createElement('a'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| subA.href = `#${h3.id}`; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const subSpan = document.createElement('span'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| subSpan.textContent = h3.textContent?.trim() ?? ''; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| subA.appendChild(subSpan); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| subLi.appendChild(subA); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| subList.appendChild(subLi); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| li.appendChild(subList); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list.appendChild(li); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| return true; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| // Scalar renders async, so observe for headings to appear | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| if (!buildToc()) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| const observer = new MutationObserver(() => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| if (buildToc()) observer.disconnect(); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| observer.observe(document.body, { childList: true, subtree: true }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Comment on lines
+52
to
+57
There was a problem hiding this comment. The
Suggested change
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| </script> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| <style> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| nav :global(ul) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| padding: 0; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list-style: none; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| nav :global(a) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| --pad-inline: 0.5rem; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display: block; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| border-radius: 0.25rem; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| padding-block: 0.25rem; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| padding-inline: var(--pad-inline); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| line-height: 1.25; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color: var(--sl-color-gray-3); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| font-size: var(--sl-text-xs); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| text-decoration: none; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| nav :global(a:hover) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color: var(--sl-color-white); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| nav :global(a[aria-current='true']) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color: var(--sl-color-text-accent); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| nav :global(li > ul > li > a) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| padding-inline-start: calc(1rem + var(--pad-inline)); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| </style> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,13 @@ | ||
| --- | ||
| import Default from "@astrojs/starlight/components/TableOfContents.astro"; | ||
|
|
||
| import ScalarTableOfContents from "../molecules/ScalarTableOfContents.astro"; | ||
| import TelegramInvite from "../molecules/TelegramInvite.astro"; | ||
|
|
||
| const { starlightRoute } = Astro.locals; | ||
| const isApiReference = starlightRoute.slug === "ensapi/reference/api-reference"; | ||
| --- | ||
|
|
||
| {isApiReference ? <ScalarTableOfContents /> : <Default />} | ||
| <br /> | ||
| <TelegramInvite /> |
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,53 @@ | ||||||||||||||||||||
| --- | ||||||||||||||||||||
| title: ENSApi API Reference | ||||||||||||||||||||
| description: Interactive API reference documentation for ENSApi endpoints. | ||||||||||||||||||||
| sidebar: | ||||||||||||||||||||
| label: API Reference | ||||||||||||||||||||
| tableOfContents: | ||||||||||||||||||||
| minHeadingLevel: 6 | ||||||||||||||||||||
| maxHeadingLevel: 6 | ||||||||||||||||||||
|
Comment on lines
+6
to
+8
There was a problem hiding this comment. PR description mentions the API reference page uses |
||||||||||||||||||||
| --- | ||||||||||||||||||||
|
notrab marked this conversation as resolved.
|
||||||||||||||||||||
|
|
||||||||||||||||||||
| import { ScalarComponent } from "@scalar/astro"; | ||||||||||||||||||||
| import openapiSpec from "@workspace/docs/docs.ensnode.io/ensapi-openapi.json"; | ||||||||||||||||||||
|
|
||||||||||||||||||||
| <ScalarComponent | ||||||||||||||||||||
| configuration={{ | ||||||||||||||||||||
| content: openapiSpec, | ||||||||||||||||||||
|
Comment on lines
+12
to
+16
There was a problem hiding this comment. Importing the full OpenAPI JSON at build time will bundle the entire spec into the page’s JS payload. If Scalar supports loading from a URL or static asset path, consider switching to that approach to reduce client bundle size and improve initial load performance (especially as the spec grows).
Suggested change
Member
There was a problem hiding this comment. Doing so would (URL) mean we can't view in our preview deployments the upcoming API spec changes. Need to investigate the static asset path though... I assume this means just putting it in the
Member
Author
There was a problem hiding this comment. i think not worth optimizing, is a-ok
Member
There was a problem hiding this comment. I looked to implement this last week but there is a lot more involved that would require changing the CI steps so we output the spec to the public directory. We could change the output directory of the generated spec (and what our CI check looks at), or copy on build to the I'm more inclined to follow option A to move the output directory to |
||||||||||||||||||||
| theme: "none", | ||||||||||||||||||||
| agent: { disabled: true }, | ||||||||||||||||||||
| hideDownloadButton: true, | ||||||||||||||||||||
| hiddenClients: true, | ||||||||||||||||||||
| telemetry: false, | ||||||||||||||||||||
| defaultOpenAllTags: true, | ||||||||||||||||||||
| expandAllResponses: true, | ||||||||||||||||||||
| hideClientButton: true, | ||||||||||||||||||||
| hideSearch: true, | ||||||||||||||||||||
| showOperationId: true, | ||||||||||||||||||||
| showSidebar: false, | ||||||||||||||||||||
| showDeveloperTools: "never", | ||||||||||||||||||||
| isEditable: false, | ||||||||||||||||||||
| isLoading: false, | ||||||||||||||||||||
| hideTestRequestButton: false, | ||||||||||||||||||||
| forceDarkModeState: "light", | ||||||||||||||||||||
| hideDarkModeToggle: true, | ||||||||||||||||||||
| withDefaultFonts: true, | ||||||||||||||||||||
| expandAllModelSections: true, | ||||||||||||||||||||
| customCss: ` | ||||||||||||||||||||
| .light-mode { | ||||||||||||||||||||
| --scalar-color-1: #121212; | ||||||||||||||||||||
| --scalar-color-2: rgba(0, 0, 0, 0.6); | ||||||||||||||||||||
| --scalar-color-3: rgba(0, 0, 0, 0.4); | ||||||||||||||||||||
| --scalar-color-accent: var(--color-primary); | ||||||||||||||||||||
| --scalar-background-1: var(--color-background); | ||||||||||||||||||||
| --scalar-background-2: #f6f5f4; | ||||||||||||||||||||
| --scalar-background-3: #f1ede9; | ||||||||||||||||||||
| --scalar-background-accent: color-mix(in srgb, var(--color-primary) 6%, transparent); | ||||||||||||||||||||
| --scalar-border-color: var(--color-border-light); | ||||||||||||||||||||
| } | ||||||||||||||||||||
| .scalar-mcp-layer { display: none !important; } | ||||||||||||||||||||
| .section { padding-inline: 0 !important; } | ||||||||||||||||||||
| .main-pane { isolation: auto !important; } | ||||||||||||||||||||
| `, | ||||||||||||||||||||
| }} | ||||||||||||||||||||
| /> | ||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The PR description notes overriding Starlight’s
TwoColumnContentto always render the right sidebar column, but this integration’scomponentslist does not register aTwoColumnContentoverride and there’s no override file undersrc/components/overrides. If that override is required for the new reference page layout (e.g., keeping the right sidebar when TOC is disabled), it should be included here; otherwise the PR description should be updated to reflect the actual approach.