OpenAPI Phase 5: docusaurus-plugin-openapi-docs + generated artifacts#3
Merged
OpenAPI Phase 5: docusaurus-plugin-openapi-docs + generated artifacts#3
Conversation
Wires the HTTP API reference to the OpenAPI spec shipped inside
@atomicmemory/atomicmemory-core. docusaurus-plugin-openapi-docs
generates 29 .mdx pages + sidebar.ts from the spec on every
prestart/prebuild; the artifacts are committed so fresh clones
render the site without invoking gen first.
Deps:
- @atomicmemory/atomicmemory-core (file:../Atomicmemory-core for
now — needs to switch to a published version ^1.0.x before this
branch is merged)
- docusaurus-plugin-openapi-docs + docusaurus-theme-openapi-docs
docusaurus.config.ts:
- register the plugin under id 'openapi', pointing specPath at
require.resolve('@atomicmemory/atomicmemory-core/openapi.yaml')
so the generator tracks whatever core version is installed
- add the theme to themes[]
- set docs.docItemComponent='@theme/ApiItem' (required for the
generated api.mdx renderers)
package.json scripts:
- gen:api / clean:api (plugin CLI passthroughs)
- prestart + prebuild both run gen:api so local dev and CI build
always regenerate from the latest core spec
sidebars.ts:
- import the plugin-generated sidebar.ts and plug it into
apiReferenceSidebar under a "HTTP API" category
- keep hand-authored conventions.md as the anchor intro page
Deletions: 8 hand-written markdown pages under docs/api-reference/
http/ (ingest, search, list-get-delete, consolidate-decay-cap,
lessons, audit, config, agents). Their content was a manual port of
atomicmemory-core/docs/api-reference.md; the generated pages replace
them 1:1 and drift is no longer possible.
Stale-link fixes:
- docusaurus.config.ts footer → /api-reference/http/ingest-memory
- docs/quickstart.md "Full API reference" link → ingest-memory
- docs/sdk/guides/atomicmemory-backend.md table row links → the
5 new per-route slugs (ingest-memory, search-memories, etc.)
Codex flagged three real issues on the Phase 5 PR:
1. file: dep broke CI / Pages. @atomicmemory/atomicmemory-core pinned
to file:../Atomicmemory-core resolves only in this local workspace;
deploy.yml's `npm ci` would have failed on GitHub Actions.
Fix: vendor core's openapi.yaml into vendor/atomicmemory-core-openapi.yaml
and point docusaurus.config.ts at the local file. Removed the
@atomicmemory/atomicmemory-core dependency entirely. Add
scripts/vendor-core-spec.mjs + `npm run vendor:spec` for pulling a
refreshed spec from a newly-installed core package; workflow is:
npm install @atomicmemory/atomicmemory-core@<version>
npm run vendor:spec
npm run regen:api
git commit
2. prestart/prebuild didn't actually refresh anything. The plugin's
gen-api-docs only writes files that don't already exist, so with
the generated .mdx / sidebar.ts committed in the repo, rerunning
never picked up upstream spec changes.
Fix: add `regen:api` = `clean:api && gen:api`, and switch
prestart/prebuild to call regen:api. Every local dev start and
every CI build now nukes the previous artifacts before regenerating.
3. conventions.md overstated envelope consistency. The page said
"all endpoints return a consistent { error } format" but the
generated update-config page already documents richer 400
(with detail + rejected) and 410 (with detail) envelopes.
Fix: rewrite the Error responses section to (a) explicitly call
the basic { error } shape canonical, (b) spell out the two
richer PUT /v1/memories/config envelopes with full JSON examples,
and (c) annotate the status table so each row notes which
envelope applies. The hand-maintained intro page now matches
the generated reference.
All three checks pass: clean npm ci works without ../Atomicmemory-core,
regen:api refreshes artifacts each run, build still succeeds.
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.
Summary
Wires the HTTP API reference to the OpenAPI spec shipped inside
@atomicmemory/atomicmemory-core.docusaurus-plugin-openapi-docsgenerates 29.mdxpages +sidebar.tsfrom the spec on everyprestart/prebuild; artifacts are committed so a fresh clone +npm install+npm startworks without invoking gen first.This PR currently installs core via
file:../Atomicmemory-core. Before merging tomainwe need to:@atomicmemory/atomicmemory-core@1.0.1(or equivalent) from the core repo'sarchitecture2branch — that branch has PR #28 merged and shipsopenapi.yaml+openapi.jsonin the npm tarball.package.jsonto"@atomicmemory/atomicmemory-core": "^1.0.1".npm run gen:api) and re-commit if any drift shows up.Until step 1 happens, the committed artifacts are source-of-truth — consumers without
../Atomicmemory-corenearby can still inspect the rendered site.Config changes
docusaurus.config.ts
docusaurus-plugin-openapi-docs(id:openapi) withspecPath: require.resolve('@atomicmemory/atomicmemory-core/openapi.yaml').docusaurus-theme-openapi-docstothemes[].docs.docItemComponent: '@theme/ApiItem'(required for the plugin's renderers).package.json scripts
gen:api/clean:api(plugin CLI passthroughs).prestart+prebuildboth rungen:api→ local dev and CI always regenerate from the latest core spec.sidebars.ts
sidebar.tsand plug it underapiReferenceSidebar → HTTP API.conventions.mdas the anchor intro page.Deletions
8 hand-written markdown pages under
docs/api-reference/http/(ingest, search, list-get-delete, consolidate-decay-cap, lessons, audit, config, agents). Their content was a manual port ofatomicmemory-core/docs/api-reference.md; generated pages replace them 1:1 and drift is no longer possible.Stale-link fixes
docusaurus.config.tsfooter →/api-reference/http/ingest-memorydocs/quickstart.md"Full API reference" link →ingest-memorydocs/sdk/guides/atomicmemory-backend.mdtable row links → the 5 new per-route slugs (ingest-memory,search-memories,list-memories,get-memory,delete-memory)Test plan
npm installresolves (file: dep) + installs pluginnpm run gen:api— creates 29 api.mdx + per-route schema/params JSON + sidebar.tsnpm run build— completes successfully; no broken-link throwsbuild/api-reference/http/ingest-memory.html+ 28 other operation pages present in dist/api-reference/http/ingest-memory→ param tables, request schema, response schema all render