feat(docs-ui): OpenAPI overview at docs root + open active protocol#157
Merged
Conversation
… found'
The docs root (/docs) is ours to define, but it was routing to the
404 surface ('/ does not exist') because parseRouteHash returns the
canonical '/' for the root and renderContent treated any non-empty
activePagePath as a page lookup that missed.
Now the root renders an OpenAPI-driven landing (ReDoc-style):
- title + version badge
- contact / license line (when present)
- servers list straight from spec.servers
- info.description rendered as markdown
followed by the existing endpoint list. A genuine non-root path with
no matching page still shows 'Page not found'.
renderDocsOverview() reads only from the in-page spec (no new module
imports, so inline + external delivery are both unaffected). Adds
.docs-overview* styles to the content style-section.
Regression test in test/docs/root-overview.int.test.ts evals the
bundled runtime in jsdom and asserts the root shows the overview
(title/version/servers/description/contact), degrades to just a title
when info/servers are absent, and still 404s a real missing path.
…xpanded nav Two UX fixes for the docs root (/docs): 1. The sidebar was empty at root because renderSidebar early-returned on any truthy activePagePath — and the root path is '/' (truthy). Now the root renders the active protocol's endpoint groups, expanded (appendSidebarGroup already defaults to expanded). The same '/' truthiness left the protocol tab un-highlighted; fixed via isRoot. 2. Protocol order is now a logical priority — http > graphql > websocket > jsonrpc > grpc > streams > tcp > udp — so the docs open on what a consumer most likely came to read (HTTP when present), and the tab order follows the same priority instead of detection order. Extends test/docs/root-overview.int.test.ts: at root the HTTP endpoints are listed and not collapsed, the HTTP tab is active, and tabs order by priority (http first, graphql before udp).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The docs root (
/docs) is ours to define but was showing "Page not found" (the root path/is truthy, so it hit the 404 surface and the sidebar early-returned).Now the root:
spec.servers, andinfo.descriptionas markdown — then the endpoint list.http>graphql>websocket>jsonrpc>grpc>streams>tcp>udp) and lists its endpoints in the sidebar expanded, with the active protocol tab highlighted.A genuine non-root missing path still shows "Page not found".
renderDocsOverview()reads only from the in-page spec (no new module imports → inline + external delivery unaffected).Tests
test/docs/root-overview.int.test.tsevals the bundled runtime in jsdom: root shows the overview, lists HTTP endpoints (not collapsed), HTTP tab active, tabs ordered by priority, and real missing paths still 404. Full suite 3388/3388, tsc clean.🤖 Generated with Claude Code