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
41 lines
1.6 KiB
Markdown
41 lines
1.6 KiB
Markdown
# 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
|
|
1) Build the consolidated spec:
|
|
```bash
|
|
pnpm api:build # produces out/api/stella.yaml
|
|
pnpm api:lint # optional: spectral lint
|
|
pnpm api:compat # optional: compat check vs stella-baseline.yaml
|
|
```
|
|
2) Generate static reference:
|
|
```bash
|
|
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.
|
|
|
|
3) Verify determinism/offline:
|
|
- Compare hashes of `out/api/reference/` across two runs → must match.
|
|
- Open `out/api/reference/index.html` without network access.
|
|
|
|
## 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.sha256` manifest 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.
|