docs(savanna): REST API reference with OpenAPI-generated endpoint pages

[ngarakapati]

Summary

Replaces the monolithic Savanna control-plane API docs with a full REST API reference module: task-oriented overview, per-endpoint pages generated from the vendored OpenAPI catalog, and tooling to keep nav and pages in sync.

Docs & structure

• Split _catalog/endpoints.adoc into one Antora page per allowlisted endpoint, grouped nav (workgroups, workspaces, cloud providers, add-ons, backups, IP allow list, org users, etc.).
• New overview, Create an API key, and data-plane APIs pages; authentication and standalone definitions page removed (schemas live inline on each endpoint page).
• API key how-to moved from Administration into rest-api; cross-links updated across admin and overview.
• Run in Postman on the overview via page-postman-url (hosted collection; no checked-in Postman artifact).

Build & authoring

• lib/split-endpoints.js — parses catalog + OpenAPI, enforces a public route allowlist, writes pages/endpoints/* and nav.adoc.
• lib/api-page.js — renders each page (parameters, expanded schemas, multi-language request samples, response examples) with curated api-descriptions.json / api-examples.json.
• npm run endpoints:split and gulp devHot / npm run dev for local preview with ../antora-ui bundle rebuild.

Companion change: requires the matching antora-ui PR for section tabs, API sidebar (method badges), and the two-column API reference layout.

Test plan

• From cloud-docs: npm run endpoints:split completes without errors.
• PLAYBOOK=antora-playbook.local.yml npm run dev (with local antora-ui bundle) and open Savanna → API reference.
• Overview links, nav groups, and a sample of GET/POST endpoint pages render (request bar, schemas, language samples, responses).
• Run in Postman on the overview opens the hosted collection.
• Administration → Settings → API keys links to rest-api:create-api-key.
• Spot-check aliases: old authentication, definitions, and index-previous URLs resolve to the overview where configured.

[netlify]

✅ Deploy Preview for thriving-strudel-91d4a9 ready!

Name	Link
🔨 Latest commit	1b05375
🔍 Latest deploy log	https://app.netlify.com/projects/thriving-strudel-91d4a9/deploys/6ab64c917f84ff0008abe36e
😎 Deploy Preview	https://deploy-preview-175--thriving-strudel-91d4a9.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Tushar-TG-14]

@ngarakapati

1. I noticed the generator checks that catalog endpoints are in the public allowlist, but does it also verify that every endpoint in the allowlist exists in the catalog and gets generated? Otherwise, could an endpoint be accidentally omitted without the build failing?
2. Before merging, can we confirm the generated pages have been tested with the exact #56 ui-bundle.zip, especially one GET and one POST endpoint, including request samples, response tabs, schemas, copy buttons, and API navigation?
3. For the old endpoint URLs, are we preserving redirects/aliases for existing external bookmarks as well, or are we only updating internal xrefs to the new endpoint pages?

[ngarakapati]

Thanks @Tushar-TG-14.

1. Yeah - it only failed if the catalog had something that isn't in the allowlist. The other direction wasn't checked, so an allowlist endpoint missing from the catalog would just not get a page. I added that check; the generator now fails if either side is missing.

2. Yes. adding Nov 393 release notes #56 is merged, and the deploy preview was rebuilt against that bundle. I went through a GET and a POST (samples, response tabs, schemas, copy, nav).

3. Internal xrefs were rewritten to the new pages. We're not adding aliases/redirects for the old endpoints.html#_https_... hashes. Those bookmarks will 404.