docs(api): a browsable reference, and one page instead of three

[gustavosbarreto]

The documentation this site replaced rendered the OpenAPI specification as a reference you could read and search. The rewrite dropped it, and the redirect for the old reference URL landed on a page that hands over a YAML file instead.

The reference is back, at /api/reference, one edition at a time behind a switch. It is rendered by Redoc from specifications the site now serves itself, bundled from openapi/spec during the build the same way the release bundles are, so they describe the tree they ship with. That matters beyond tidiness: the bucket the release bundles live in only allows docs.shellhub.io, so a page fetching them would break on any other address the site is served from.

It stands outside the documentation layout on purpose — Redoc brings its own two-column reading surface and wants the window — but carries the same header, so it reads as part of the site rather than a different one. It is reached from the REST API page instead of sitting in the navigation beside pages that read like pages.

Authentication, keys and the specification were three pages telling one story, and two of them repeated each other word for word: the list of routes an API key cannot reach, and the note that a key carries a role, appeared in both. They are now one page, in the order somebody works — authenticate, create the key, learn what it cannot do, rotate it, read a refusal, page a list, find the specification. The ten pages that linked the old two link the section they meant, and the old URLs redirect there.

[github-actions]

Claude finished @gustavosbarreto's task in 3m 32s —— View job

---

Code Review Complete

Reviewed 19 files across code quality, security, testing, language patterns,
and architecture — no new issues found. The code looks good as-is.

A few things I checked and confirmed hold:

• Build wiring — the openapi npm script's config path ../../../openapi/redocly.yaml resolves to the repo-root config, whose community-customer@v1 / cloud-customer@v1 / enterprise-customer@v1 aliases all exist; the bundled filenames ({edition}-openapi.yaml) match what reference.astro fetches and what the ## The specification table links; public/openapi/ is gitignored and @redocly/cli is in both package.json and the lockfile.
• Security — the ?edition= query param is allowlisted via buttons.some(b => b.dataset.edition === wanted) before it can reach download.href, the Redoc URL, or replaceState, falling back to "community" otherwise. The error-path innerHTML is a static literal. No DOM XSS or open redirect.
• Links & redirects — no remaining references to the deleted /api/api-keys or /api/openapi pages anywhere in the docs tree; the reworked links resolve to real headings, and every old redirect target (/api, /api/reference) exists.
• Astro/React — <ShellHubLogo /> / <GithubIcon /> render server-side (the @astrojs/react integration is configured and used by other .astro pages); define:vars, the data-edition query, and the CDN onload/onerror guards are all correct.

---

To request another review round, comment /review.
· docs/api-reference

[github-actions]

Documentation preview: https://3c91ecac.shellhub-docs.pages.dev

[github-actions]

Documentation preview: https://59cb7739.shellhub-docs.pages.dev

[github-actions]

Documentation preview: https://781f964b.shellhub-docs.pages.dev

[github-actions]

Documentation preview: https://e825e6f0.shellhub-docs.pages.dev