Migrate API docs from Apiary to OpenAPI 3.1 + Scalar on GitHub Pages

[adamkrellenstein]

Why

counterpartycore.docs.apiary.io no longer renders (Apiary's docs-v4 renderer returns HTTP 500 on our blueprint, while other Apiary sites still work). There is no fixing it: Oracle is retiring Apiary (announced shutdown September 2026, paid plans deprecated since 2018), and the entire API Blueprint toolchain is archived on GitHub — the api-blueprint spec itself (2023), drafter (2024), and dredd (2024), which our CI depends on. The blueprint itself is valid (parses with drafter, warnings only); the platform is simply dead.

What

Full migration to the current industry-standard stack, keeping the existing regtest-based generation workflow intact:

• genapidoc.py now emits OpenAPI 3.1 (openapi.json at the repo root) instead of API Blueprint (apiary.apib). Same inputs as before: routes.ROUTES, docstrings, live example responses from the regtest node, apicache.json caching, mainnet address/hash conversion. Intro prose moved from blueprint-template.md to apidoc/intro.md (rendered as the spec description); group docs become tag descriptions (incl. new apidoc/group-mempool.md).
• Schemathesis replaces dredd for contract testing in scenarios_test.py: runs the documented examples against the live regtest node (--phases=examples --checks=not_a_server_error, same route exclusions as the old dredd config). dredd.yml, dreddhooks.py and the npm install dredd CI step are removed; schemathesis==4.21.4 replaces dredd_hooks in requirements.
• Docs hosting: Scalar on GitHub Pages at https://apidocs.counterparty.io/ — apidocs/index.html (version-pinned CDN bundle with subresource integrity) + a new apidocs.yml workflow that deploys on pushes to master touching openapi.json. Pages is already switched to workflow-based deploys with the custom domain configured; DNS (CNAME at Namecheap) is in place.
• API server: /v2/openapi.json serves the spec (replacing /v2/blueprint); GET /v2/ root now returns documentation: https://apidocs.counterparty.io/ and an openapi field with the raw-spec URL (replacing blueprint).
• The "Regtest Scenarios" CI job now uploads the regenerated openapi.json as an artifact; the committed spec comes from that artifact (run 27237951828).

Breaking changes (for the next release notes)

• GET /v2/blueprint removed — replaced by GET /v2/openapi.json.
• In the GET /v2/ response, the blueprint field is replaced by openapi, and documentation now points to https://apidocs.counterparty.io/.

Verification

• CI Regtest Scenarios green: full pipeline ran end-to-end — scenario suite, OpenAPI generation against the live node, then Schemathesis: 181/191 operations selected (exclusions working), 347 API calls generated, 347 passed, examples phase 176 passed / 5 skipped.
• Committed spec passes openapi-spec-validator (OpenAPI 3.1); contains no regtest data (bcrt1 count: 0; hashes converted to sequential placeholders); 182/191 operations carry real example responses.
• Scalar page rendered in headless Chrome against this exact spec: all 29 groups, intro sections, and operations render; no JS errors.
• New unit test test_apiserver_openapi_spec covers the /v2/openapi.json route (status, content type, version, no-regtest-data); full apiserver suite passes (34 tests).
• Workflows pass actionlint (only pre-existing warnings about setup-python@v3/actions-rs).

Note: this PR also fixes the Pylint Scanner job, which it had inadvertently broken: installing schemathesis bumps jsonschema to ≥4.18, whose resolver rewrite crashes the unmaintained pylint2sarif. The scanner job now pins jsonschema<4.18 (scan-only env) and upload-sarif is bumped to v3 (v2 is deprecated). Root cause reproduced and fix verified in a clean local venv.

Rollout

Docs go live when this reaches master (the Pages workflow triggers on master pushes). Companion PRs updating links, to merge once the site is live: CounterpartyXCP/Documentation#258 and CounterpartyXCP/Website#24.

@ouziel-slama — this touches your doc-generation pipeline; review much appreciated.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.34%. Comparing base (4c2651c) to head (bf58061).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3401      +/-   ##
===========================================
+ Coverage    91.26%   91.34%   +0.08%     
===========================================
  Files          113      113              
  Lines        15671    15671              
===========================================
+ Hits         14302    14315      +13     
+ Misses        1369     1356      -13     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.