Skip to content

Turn each OpenAPI page into sidebar entries that follow edits in dev - #159

Draft
matthewmr-eqty wants to merge 2 commits into
feat/mic-73-openapi-modelfrom
feat/mic-73-openapi-loader-nav
Draft

matthewmr-eqty wants to merge 2 commits into
feat/mic-73-openapi-modelfrom
feat/mic-73-openapi-loader-nav

Conversation

@matthewmr-eqty

Copy link
Copy Markdown
Contributor

Need

A service's API reference should appear in the sidebar and in every page-listing feature (twins, search, versions) like any other page, and stay current while an author edits in astro dev.

Problem

The glob loader rewrites entries on its own schedule, one file watcher serves all 27 content collections, and the nav derives placement from the entry id, which splits operation ids into folders and title-cases tag names.

Change

docsLoader fans each openapi: page out into a model entry and one entry per operation, re-expanded on spec or page edits, serialised per page. Operations inherit draft, hidden and noIndex. Generated entries carry their sidebar placement; tags arrive as virtual groups; method badges are text-only. A spec outside the content directory, or a generated URL that collides with an authored page, fails the build. A route-side helper was rejected: it would bypass every page-listing feature.

Evidence

155 docs tests pass, 24 of them new. In a live astro dev on this branch: adding and removing a path updated the sidebar without a restart, deleting the file removed its rows and logged the missing path, restoring it brought them back, prose edits and restarts kept the rows, and saving _group.yaml no longer logs a schema error. Lint, format check and build pass.

Not covered

No operation page renders yet; routes and components are the next PR. Node warns about more than 50 watcher listeners on dev start.

Flow

edit _api.json or api.mdx
        │
  shared watcher ──▶ glob loader (drops _ files)
        │
  docsLoader listener ──▶ expand(page), one run at a time
        │
  store: page/~api + page/operations/<slug>
        │
  docsNav ──▶ page group ▸ tag groups ▸ GET rows

Review focus

classify in src/nav.ts changes for every site: pages without navIndex or navPlacement take the old path unchanged, and the existing nav tests are only appended to. Read in this order: openapi/fan-out.ts, openapi/expand.ts, loaders.ts, then nav.ts and runtime/lib/nav-data.ts.

matthewmr-eqty and others added 2 commits September 24, 2026 12:03
Need: every page-listing feature (sidebar, twins, search, versions) should see API operations like any other page.
Problem: the glob loader rewrites entries on its own, and one watcher serves every collection in dev.
Solution: the loader fans each openapi page out into model and operation entries that follow edits and fail on collisions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Need: each service's reference expands into its tags, with a method on every operation row.
Problem: the nav derives place from the id, which splits apiv1api-keys/get into a folder, and title-cases tag names.
Solution: generated entries carry their placement, tags arrive as virtual groups, and a hidden reference stays hidden.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@matthewmr-eqty
matthewmr-eqty added this pull request to stack #161 September 24, 2026 17:26
@matthewmr-eqty
matthewmr-eqty marked this pull request as draft October 6, 2026 19:46
@matthewmr-eqty
matthewmr-eqty marked this pull request as draft October 6, 2026 19:46
@matthewmr-eqty
matthewmr-eqty removed this pull request from stack #161 October 6, 2026 20:36
@matthewmr-eqty
matthewmr-eqty added this pull request to stack #191 October 6, 2026 20:36

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant