Add built node RPC OpenAPI spec for GitBook (stacks-core b62be8ee9)

[werner-stacks]

Bundled from stacks-core docs/rpc at b62be8ee9 with @redocly/cli 2.19, then normalized so each schema appears once under its declared name. Includes the normalize script and rebuild instructions.

Description

The "Stacks Node RPC" API reference on docs.stacks.co (https://docs.stacks.co/reference/api/stacks-node-rpc) is generated by GitBook from an OpenAPI spec. Today that spec is a one-off file someone uploaded to GitBook by hand. Nobody can say exactly how it was built, and it has drifted from stacks-core.

This PR adds a reproducible build of that spec to this repo, so GitBook can load it from a fixed URL:

• openapi/stacks-node-rpc/stacks-node-rpc.b62be8ee9.json: the spec, built from stacks-core docs/rpc/ at commit b62be8ee94f2a08dc58d5ff6809a6d08b813c3e9 (main, after stacks-core PR #7691).
• openapi/stacks-node-rpc/normalize.py: a short script that cleans up the bundled spec (explained below).
• openapi/stacks-node-rpc/README.md: how to rebuild and update it.

Merging this PR does not change the live site. After it merges, the GitBook spec is pointed at the raw URL of this file, pinned to the merge commit. That second step is what updates the node RPC pages.

Why it is done this way

Why not point GitBook at stacks-core directly? The spec in stacks-core is split across 97 files that reference each other (openapi.yaml plus components/schemas/*.yaml and components/examples/*.json). GitBook needs one self-contained file, so the split files have to be bundled first.

Why the normalize script? The standard bundler, Redocly, names every component after its file (for example contract-interface.schema) in addition to the name openapi.yaml gives it (ContractInterface). The raw bundle has 114 schemas, 55 of them duplicates, and GitBook lists every one on the models page (https://docs.stacks.co/reference/api/stacks-node-rpc/models). The script folds each file-named copy into its declared name, gives the 4 schemas that have no declared name a proper one (GetStackerSetPox4, GetStackerSetPox5, Principal, StandardPrincipal), and rewrites every reference to match. The result has 59 schemas and the same 57 endpoints as the source, and redocly lint gives the same result as on the source (valid, 19 warnings). No content is changed.

Why a file in this repo, pinned to a commit? A pinned URL means the live reference only changes when someone deliberately rebuilds and re-points it, and anyone can see exactly which stacks-core commit the published reference came from. A hand upload to GitBook leaves no such record.

Why a top-level openapi/ folder? Each GitBook space syncs its own folder under docs/. A top-level folder is outside every space, so GitBook does not turn the JSON or the script into a page.

Why Redocly 2.19? It is the version stacks-core's own CI pins to lint this spec.

What changes on docs.stacks.co once GitBook points at this file

• The /v2/pox example lists all 15 epochs (Epoch10 through Epoch41) and all 5 PoX contract versions, matching mainnet today (it currently shows only Epoch0, Epoch1, pox and pox-2).
• /v3/stacker_set shows separate response shapes and examples for PoX-4 and PoX-5 cycles.
• The contract interface epoch field is described as the epoch the contract was deployed in.
• The models page lists each object once, under its proper name.

These come from stacks-core PR #7691, which is merged but not yet reflected on the site.

How to verify

Run the commands in openapi/stacks-node-rpc/README.md from a clean checkout. The rebuilt file's sha256 should be 6bfbdf37b0380126035dfe4e46c7fbf7b4f4e8000c6e0a2979808910a48c2b32.