Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions openapi/stacks-node-rpc/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Node RPC OpenAPI spec for GitBook

Source: stacks-network/stacks-core `docs/rpc/` at commit `b62be8ee94f2a08dc58d5ff6809a6d08b813c3e9` (main after PR #7691, 2026-10-06).
GitBook spec slug: `stacks-node-rpc-api-dereferenced-new` (org `hoh4mQXTl8NvI3cETroY`).

## Why the extra step

`redocly bundle` turns every schema file into a component named after the file (`contract-interface.schema`), next to the name `openapi.yaml` declares (`ContractInterface`). The bundle has 114 schemas, 55 of them duplicates; GitBook lists each one on the models page. `normalize.py` folds each file-named component into its declared name, renames the 4 that have no declared name (`GetStackerSetPox4`, `GetStackerSetPox5`, `Principal`, `StandardPrincipal`) and rewrites every reference. Result: 59 schemas, 57 paths, 57 operations, same `redocly lint` result as upstream `openapi.yaml` (valid, 19 warnings).

## Rebuild

Run from a checkout of stacks-network/docs. Requires git, Node.js with npx, and Python 3.

```bash
COMMIT=b62be8ee94f2a08dc58d5ff6809a6d08b813c3e9
SHORT=${COMMIT:0:9}
OUT="$PWD/openapi/stacks-node-rpc"
TMP=$(mktemp -d)
git clone -q --filter=blob:none --no-checkout https://github.com/stacks-network/stacks-core "$TMP/core"
git -C "$TMP/core" sparse-checkout set docs/rpc
git -C "$TMP/core" checkout -q "$COMMIT"
cd "$TMP/core/docs/rpc"
npx -y @redocly/cli@2.19 bundle openapi.yaml -o "$TMP/bundle.json" # 2.19 = the version stacks-core CI pins
python3 "$OUT/normalize.py" "$TMP/bundle.json" "$OUT/stacks-node-rpc.$SHORT.json"
npx -y @redocly/cli@2.19 lint "$OUT/stacks-node-rpc.$SHORT.json"
cd - >/dev/null
```

sha256 of `stacks-node-rpc.b62be8ee9.json`: `6bfbdf37b0380126035dfe4e46c7fbf7b4f4e8000c6e0a2979808910a48c2b32`

## Updating

When stacks-core changes `docs/rpc`, set `COMMIT` to the new commit (prefer a release tag's commit), rebuild, add the new file next to the old one, and point the GitBook spec at the new raw URL pinned to the docs merge commit. Old files can be removed once GitBook no longer points at them.
47 changes: 47 additions & 0 deletions openapi/stacks-node-rpc/normalize.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
"""Collapse redocly's file-named components into the names declared in openapi.yaml."""
import json, re, sys
src, out = sys.argv[1], sys.argv[2]
d = json.load(open(src))
s = d['components']['schemas']
P = '#/components/schemas/'
rename = {}
# 1. declared alias X -> {$ref: P+F}: move F's body into X
for k, v in list(s.items()):
if '.' not in k and isinstance(v, dict) and list(v) == ['$ref'] and v['$ref'].startswith(P):
f = v['$ref'][len(P):]
if '.' in f and f not in rename:
rename[f] = k
# 2. remaining file-named components get a PascalCase name
def pascal(f):
stem = f.removesuffix('.schema')
return ''.join(w[:1].upper() + w[1:] for w in re.split(r'[-_.]', stem))
for k in list(s):
if '.' in k and k not in rename:
n = pascal(k)
assert n not in s and n not in rename.values(), (k, n)
rename[k] = n
def walk(o):
if isinstance(o, dict):
for key, v in list(o.items()):
if isinstance(v, str) and v.startswith(P) and v[len(P):] in rename:
o[key] = P + rename[v[len(P):]]
else:
walk(v)
elif isinstance(o, list):
for v in o: walk(v)
new = {}
for k, v in s.items():
if k in rename: continue
if k in rename.values() and isinstance(v, dict) and list(v) == ['$ref']:
f = v['$ref'][len(P):]; new[k] = s[f]; continue
new[k] = v
for f, n in rename.items():
if n not in new: new[n] = s[f]
d['components']['schemas'] = new
walk(d)
txt = json.dumps(d)
left = re.findall(r'#/components/schemas/([A-Za-z0-9_.-]+)', txt)
assert not [x for x in left if x not in new], set(x for x in left if x not in new)
assert not [k for k in new if '.' in k]
json.dump(d, open(out, 'w'), indent=2)
print(len(s), '->', len(new), 'schemas;', len([r for r in rename.values() if r not in s]), 'new names:', sorted(r for r in rename.values() if r not in s))
Loading
Loading