defuss-shadcn / Application / Scaffolds / scaffold-api-docs
API Documentation
The API reference of "Acme", the fictional workspace product of the Docs & Help template: guides, resources and one page per endpoint. Fill in a Try it form and send it - an in-browser sandbox answers, and the code samples follow every value you type. Press ⌘K to search every endpoint, parameter and guide. The same workspace also comes as a defuss-rpc API whose reference is generated from its source: Call it answers from that API in the page or from a running defuss-rpc server, with the answer in a Property Tree. Every page also exists as Markdown and as JSON (api-docs/llms.txt lists them). Part of the Application Scaffolds.
On this page (2)
§API reference
The whole reference in one source. Guides, resources and endpoints are routes (#/guides/errors, #/ref/tasks, #/ref/tasks/create) of defuss-dom-router, written from one data block in English and German; the language switch translates the frame with defuss-i18n. The search (also ⌘K) ranks every endpoint, parameter and guide with defuss-search in the language shown: BM25 at once, fused with a ColBERT model once it has loaded in the background. Try it sends the form to a sandbox in the page; the curl, JavaScript and Python samples follow the form. The defuss-rpc reference (#/rpc) is written from rpc.docs.json, which defuss-rpc schema generated from the API's source; Call it answers from that API in the page or from a running defuss-rpc server.
§How it works
A page, not a component: it composes the library and keeps its own glue small.
- One data block - the guides, the resources with their object fields and every endpoint with its parameters and status codes sit in one JSON block, in English and German. The navigation, the pages, the pager, the samples and the search index are all written from it, so a new endpoint is one entry.
- Routing - defuss-dom-router in hash mode: the introduction (
#/), a guide (#/guides/errors), a resource (#/ref/tasks) and an endpoint (#/ref/tasks/create). The current link, the breadcrumb and the pager follow the address; a new page opens at its start. See Client-side Routing. - Translation - defuss-i18n translates the frame (the header, the headings, the dialogs, the palette); on its change event the script writes the navigation and the page shown again from the data block's other language. See Translation.
- Search - defuss-search over defuss-lexicalsearch, in two steps. Keywords work at once: two BM25 indexes (an English and a German analyzer; the title weighs 3, the method and path 2, the text and parameters 1) with prefix and fuzzy matching on the last word. Meanwhile the page loads the Winzling-reranker model in the background (MoEdernColBERT 1.5M, 2.28 MB as Brotli from its pinned Hugging Face revision, checked against its SHA-256; ONNX Runtime's WASM build, 2.3 MB, comes from jsDelivr) and switches to defuss-search's tiny strategy: ColBERT encodes each language's documents once, and a query is BM25 fused with a scan over their tokens, so "how do I log in", which no keyword of the reference matches, finds the Authentication guide. The switch is defuss-search's progressive search (
createProgressiveSearch, copied into the page until its release): a query asked before the model is there runs on BM25, a model that never loads leaves BM25 answering. The full-screen page keeps the decoded model in the Cache API, so a later visit downloads nothing; the data saver keeps the search on keywords. The Command palette (data-filter="none") shows the ranked hits, how long they took and which search answered. Until the modules arrive the palette compares names. - Try it - a form per endpoint, its fields made from the parameters (an enum becomes a Select). Every keystroke writes the curl, JavaScript and Python samples again (the Code Example block's tabs and copy button); Send asks a sandbox in the page that answers like the API - 401 without a key, 400 naming the missing parameter, 404, cursors and a counting rate limit. Creating, changing and deleting change what the next request sees.
- Authorize and versions - a Dialog keeps the test key in the page; the version Select switches the samples to
/v3and shows its sunset Alert. A Swap switches dark mode; Shiki paints the code panels. - defuss-rpc reference -
src/documentation/runtime/api-docs/api.tsis the same Acme workspace as a defuss-rpc API (a class of tasks, modules of members, a stream of activity and figures with aMapand aDate), documented with JSDoc.bunx defuss-rpc schema "src/documentation/runtime/api-docs/*.ts" --out rpc.docs.jsonreads it - starting atcreateRpcServer()inserver.ts, so the unregisteredresetExample()stays out - and writes each method's description, parameters, return and yield types with their JSON Schemas. The navigation, the pages (#/rpc,#/rpc/Tasks,#/rpc/Tasks/create), the signatures and the samples (the typed client, curl, fetch) are written from that file. - Call it - one field per parameter, made from its JSON Schema (a Select for an enum or a boolean, a number or text field, a Property Tree for an object); a date string becomes a
Dateand a list aSetwhere the schema says so. The call goes to the sameapi.tsbundled into the page (js/api-docs/client.js, the arguments and the answer passed through DSON as over the wire), or to a defuss-rpc server: the form asks it for/rpc/schemafirst and says when it does not answer or lacks the method. A stream shows every value as it arrives, the answer opens in a Property Tree.bun src/documentation/runtime/api-docs/server.tsruns the example as a real server (rpcRoute inBun.serve, CORS for the page's origin); the e2e test starts it and calls it. - Markdown and JSON - the app writes its pages in the browser, which a crawler or an agent that runs no JavaScript never sees. The docs build writes every page of both references once more as
api-docs/<page>.mdand.json(runtime/api-docs/pages.ts), withindex.md,index.jsonandllms.txt; each page links its two files under its title. - Built on Docs & Help - the Docs Navigation and Docs Content blocks of the Docs & Help template, in the system's tokens: a theme from the Theme Designer restyles it. Where the page is narrower than 56rem the code goes under it, below 48rem the navigation becomes a drawer.
- Full screen - app-api-docs.html is generated from this page's example at build time, on its own bundle.
Comments, ideas or improvements? Edit this page's source on GitHub