stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
9f6e6f7fb314b06d08ae115c0e0a7e9776f74185
git.stella-ops.org/docs/api/reference/README.md
StellaOps Bot 9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Signals CI & Image / signals-ci (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-25 22:09:44 +02:00

1.6 KiB
Raw Blame History

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:

    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:

    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.