9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
API Reference Site (DOCS-OAS-62-001)
Last updated: 2025-11-25
Goal
Publish a deterministic, offline-friendly API reference site generated from the consolidated OpenAPI (out/api/stella.yaml) and integrate it into the developer portal navigation.
Generation steps
-
Build the consolidated spec:
pnpm api:build # produces out/api/stella.yaml pnpm api:lint # optional: spectral lint pnpm api:compat # optional: compat check vs stella-baseline.yaml -
Generate static reference:
pnpm api:reference # expected to write to out/api/reference/The command should:
- Use the bundled
out/api/stella.yaml. - Produce deterministic HTML/CSS/JS assets (no timestamps in bundles).
- Avoid external CDNs; fonts/assets must be local for air-gap.
- Use the bundled
-
Verify determinism/offline:
- Compare hashes of
out/api/reference/across two runs → must match. - Open
out/api/reference/index.htmlwithout network access.
- Compare hashes of
Portal integration
- Copy
out/api/reference/into the developer portal static assets under/reference/. - Add nav link “API Reference” pointing to
/reference/. - Ensure CSP allows only self-hosted assets (
default-src 'self').
Artifacts to publish
out/api/stella.yaml(signed checksum).out/api/reference/(static site; checksum manifest).out/api/reference.sha256manifest listing all files/hashes.
Notes
- Keep OpenAPI examples deterministic (sorted keys, stable ordering).
- Do not embed secrets or environment-specific URLs; use placeholders where needed.