feat: publish a multi-version API reference site via GitHub Pages

[shalk]

Summary

• The hand-written OpenAPI docs in the apollo repo only cover a fraction of the actual contract (~53 of ~152 endpoints today) and keep drifting out of sync as the spec grows. This publishes a static API reference site rendered directly from apollo-openapi.yaml, so it can't drift.
• scripts/build-docs.sh (Redocly CLI) builds one page per released git tag (vX.Y.Z/) plus the current main HEAD as next/ (labeled unreleased), copies the latest tag's build to the site root (root = latest release, not HEAD, since Portal only ever pins tagged specs), and generates a versions.html index — all driven off the live tag list, no hand-maintained version list to forget updating.
• .github/workflows/deploy-docs.yml deploys via the standard actions/upload-pages-artifact + actions/deploy-pages flow, triggered on doc-relevant pushes to main and unconditionally on every v* tag (a new release always republishes the whole multi-version site).

Test plan

• npm install && ./scripts/build-docs.sh locally — all 14 existing tags (v0.1.0..v0.3.11) plus next build successfully, correctly version-sorted (v0.3.10/v0.3.11 after v0.3.9, not lexically before it)
• Served site/ locally and verified /, /next/, /v0.1.0/, /versions.html all return 200 with expected rendered titles
• site/index.html is byte-identical to the latest tag's index.html
• After merge: enable GitHub Pages on this repo (Settings → Pages → Source → "GitHub Actions"), confirm deploy-docs.yml runs and the Pages URL resolves correctly

Open question for maintainers

This was built/tested against my fork, so README.md currently links to https://shalk.github.io/apollo-openapi/. If this merges here, that should become https://apolloconfig.github.io/apollo-openapi/ (or wherever Pages ends up hosted for this repo) — happy to push that fix once we agree on the target.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: f777b66b-b632-42b9-bf1d-816fba4ae2fb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nobodyiam]

Thanks for adding the versioned API reference site. I reproduced npm ci and the full docs build at 3ba4a84; all 14 existing tags plus next build successfully, and the current checks are green.

Please address these blocking correctness issues before merging:

1. scripts/build-docs.sh:79-84 swallows per-tag build failures and still publishes the site. A failed new release can therefore be omitted silently while the root page falls back to an older release. Please fail the build when any expected release tag cannot be rendered, unless an explicit legacy-tag allowlist is required.
2. .github/workflows/deploy-docs.yml:28-31 checks out the triggering ref. On a v* push that is the tag, so site/next is built from the tag commit rather than necessarily from the current main HEAD. Please build next explicitly from main.
3. README.md:4,14,16 points the official repository to the contributor-owned shalk.github.io site. The Pages address for this repository is https://apolloconfig.github.io/apollo-openapi/; please update the badge, main documentation link, and versions link accordingly before merging.

Non-blocking: please also consider regenerating package-lock.json against registry.npmjs.org instead of pinning the GitHub-hosted build to the Tencent mirror.

[shalk]

Thanks for the careful review. All three blocking items are addressed in 5b530cb, and the non-blocking one in 9e2a606.

1. scripts/build-docs.sh — silent per-tag failures

A tag whose spec fails to render now aborts the whole build (exit 1) instead of dropping that version and publishing anyway. No legacy allowlist turned out to be needed: I checked all 14 existing tags and every one of them contains apollo-openapi.yaml, so the remaining continue branch (tag without the spec file) is purely defensive and never fires today.

2. .github/workflows/deploy-docs.yml — next built from the triggering ref

Checkout is now pinned to ref: main, so site/next is built from current main HEAD regardless of what triggered the run. Released versions are read out of git history via git show <tag>:apollo-openapi.yaml rather than from the working tree, so they are unaffected by which ref is checked out (fetch-depth: 0 keeps every tag available).

One deliberate side effect worth calling out: on a v* push the build now runs main's copy of build-docs.sh rather than the tag's. That seems right for a docs site — the tooling should track main — but happy to change it if you'd rather the tag pin its own builder.

3. README.md — contributor-owned Pages URL

The badge, the main documentation link, and the versions link all point at https://apolloconfig.github.io/apollo-openapi/ now. That also settles the open question in the PR description.

Non-blocking: package-lock.json registry

Regenerated against registry.npmjs.org. The integrity hash is unchanged, which confirms the tarball is byte-identical and only the download host differed. npm ci verified locally.

Remaining after merge, as noted in the test plan: GitHub Pages needs to be enabled on this repository (Settings → Pages → Source → "GitHub Actions") before deploy-docs.yml can publish.

[nobodyiam]

Thanks for the updates. Re-reviewed at 9e2a606; all three blocking items and the registry suggestion are addressed.

I verified npm ci and the full docs build for all 14 release tags plus next, confirmed that the root page matches v0.3.11, and checked the generated pages and version links. Fault-injection checks also confirmed that a failed tag render aborts the build. The current CI checks pass. No blocking findings remain.

After merging, please enable GitHub Pages with GitHub Actions as the source and verify the main/tag deployment paths and the published URL.