API Reference Site (DOCS-OAS-62-001)

Last updated: 2026-05-30

Audience: Docs and platform engineers building or consuming the consolidated Stella Ops OpenAPI surface. This page records both what ships today (the aggregate-spec build) and the proposed static reference site, with each section clearly marked.

Status: The aggregate-spec build is implemented (npm run api:compose → compose.mjs). The static reference site (api:reference, out/api/reference/, the reference.sha256 manifest, and the portal integration) is proposed / NOT IMPLEMENTED — no script, CI job, or tool in the repository produces those artifacts yet. Sections describing them below are kept as forward design intent and flagged accordingly.

Goal

Publish a deterministic, offline-friendly API reference site generated from the consolidated OpenAPI spec and integrate it into the developer portal navigation.

The consolidated spec is produced by src/Api/StellaOps.Api.OpenApi/compose.mjs, which writes the aggregate to src/Api/StellaOps.Api.OpenApi/stella.yaml (the composer’s OUTPUT constant). There is currently no out/api/ output directory.

Generation steps

1. Build the consolidated spec (implemented):

   npm run api:compose   # node src/Api/StellaOps.Api.OpenApi/compose.mjs
                         # writes src/Api/StellaOps.Api.OpenApi/stella.yaml
   npm run api:lint      # optional: spectral lint over src/Api/StellaOps.Api.OpenApi/**/*.yaml
   npm run api:compat    # optional: compat diff vs baselines/stella-baseline.yaml
   

   These map to scripts in the repo-root package.json. Note the runner is npm, not pnpm, and the compose script is named api:compose (there is no api:build script).

   Related implemented scripts: npm run api:examples (example-coverage check) and npm run api:changelog (changelog generation).

2. Generate static reference — NOT IMPLEMENTED (proposed):

   # PROPOSED — no such script exists today:
   # npm run api:reference   # would write to out/api/reference/
   

   When implemented, the command should:

   • Use the bundled aggregate spec (src/Api/StellaOps.Api.OpenApi/stella.yaml).
   • Produce deterministic HTML/CSS/JS assets (no timestamps in bundles).
   • Avoid external CDNs; fonts/assets must be local for air-gap.

   Today, the repository’s only generated, byte-stable API reference output is the per-module Markdown produced by the first-party .NET docgen (src/Tools/StellaOps.OpenApi.DocGen via tools/scripts/docs/regen-from-openapi.ps1), written to docs/modules/<service>/api-reference.md from docs/modules/<service>/openapi/v1.json and guarded for byte-identity by the OpenAPI Truthfulness CI workflow (.gitea/workflows/openapi-truthfulness.yml). This is a separate pipeline from the static reference site proposed above.

3. Verify determinism/offline — NOT IMPLEMENTED (proposed):

   • Compare hashes of out/api/reference/ across two runs → must match.
   • Open out/api/reference/index.html without network access.

Portal integration — NOT IMPLEMENTED (proposed)

• 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

• src/Api/StellaOps.Api.OpenApi/stella.yaml — the implemented aggregate spec emitted by compose.mjs. (Signed-checksum publishing is not wired in this repo.)
• out/api/reference/ (static site; checksum manifest) — proposed, not produced.
• out/api/reference.sha256 manifest listing all files/hashes — proposed, not produced.

Notes

• Keep OpenAPI examples deterministic: compose.mjs already sorts paths, schemas, responses, parameters, and security schemes by key and namespaces per-service schemas/paths for stable ordering.
• Do not embed secrets or environment-specific URLs; use placeholders where needed.
• The compat baseline lives at src/Api/StellaOps.Api.OpenApi/baselines/stella-baseline.yaml (not a bare stella-baseline.yaml at the repo root).