chore: update openapi specs

[Jiloc]

Description

This PR significantly updates and expands the openapi.yaml specification for the Stacks node RPC API. It adds definitions for numerous previously undocumented V2 and V3 endpoints, refactors common parameters into reusable components for consistency, and enhances existing endpoint definitions with more accurate details, schemas, and examples.

Key changes include:

• All known RPC endpoints, including those from issue [Docs] Complete documentation of the node RPC-API #4551, are now documented.
• Fixed numerous outdated endpoints with incorrect/missing/nonexistent parameters and return types.
• The openapi.yaml has been broken down into reusable components for schemas, parameters, and examples, located in the new docs/rpc/components/ directory. All JSON schemas were converted to YAML.
• Validation: A redocly.yaml configuration has been added, and the entire specification now passes the redocly lint check.
• Correction: A minor typo in the metrics identifier for the liststackerdbreplicas endpoint has been fixed (stackedb -> stackerdb).
• Moved OpenAPI validation and docs creation CI step from stacks-core-tests.yml to ci.yml. While I was testing the new workflow, I realized that the validation would only start after the [CI / Create Test Cache / Test Archive] step, that takes more than 10 minutes and that we can move it at an earlier step.

Applicable issues

• fixes [Docs] Complete documentation of the node RPC-API #4551 by documenting a large majority of the missing RPC endpoints and addressing inconsistencies in existing ones.

Additional info (benefits, drawbacks, caveats)

Checklist

• Test coverage for new or modified code paths
• Changelog is updated
• Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
• New clarity functions have corresponding PR in clarity-benchmarking repo
• New integration test(s) added to bitcoin-tests.yml

[wileyj]

would it be possible to also address this issue in this PR?
#5214

[wileyj]

tagging @cylewitruk since #4551 was his idea

[Jiloc]

would it be possible to also address this issue in this PR? #5214

I'll open a separate PR for that!

[wileyj]

lgtm

[wileyj]

pending resolution of the the openapi validation, this seems fine

[Jiloc]

@wileyj note that in the latests changes I also moved the validation workflow to ci.yml from stacks-core-tests.yml. The step was gated by the [CI / Create Test Cache / Test Archive (pull_request)] step that isn't actually correlated

[wileyj]

@wileyj note that in the latests changes I also moved the validation workflow to ci.yml from stacks-core-tests.yml. The step was gated by the [CI / Create Test Cache / Test Archive (pull_request)] step that isn't actually correlated

hmm, i see the reasoning but i think it's better to keep under stacks-core-tests. otherwise, without some extra conditionals checking that the stacks-core-tests job was successful, this step will run every time - even if tests or other steps/jobs are failing.

it's not a bad thing necesarily (just adds noise), i just think it's better suited as part of the stacks-core-tests workflow. i'm less concerned that the create-test-cache workflow is gating this - if that fails, openapi validation shouldn't even run.

Otherwise, i think the changes still look good - just have to reach consensus on where to run it (along with the composite workflow merge)

[Jiloc]

@wileyj note that in the latests changes I also moved the validation workflow to ci.yml from stacks-core-tests.yml. The step was gated by the [CI / Create Test Cache / Test Archive (pull_request)] step that isn't actually correlated

hmm, i see the reasoning but i think it's better to keep under stacks-core-tests. otherwise, without some extra conditionals checking that the stacks-core-tests job was successful, this step will run every time - even if tests or other steps/jobs are failing.

it's not a bad thing necesarily (just adds noise), i just think it's better suited as part of the stacks-core-tests workflow. i'm less concerned that the create-test-cache workflow is gating this - if that fails, openapi validation shouldn't even run.

Otherwise, i think the changes still look good - just have to reach consensus on where to run it (along with the composite workflow merge)

I moved it back in e858b09

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.05%. Comparing base (c76743e) to head (e858b09).
Report is 82 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #6201       +/-   ##
============================================
+ Coverage    66.66%   82.05%   +15.38%     
============================================
  Files          543      546        +3     
  Lines       345656   347235     +1579     
  Branches       323      323               
============================================
+ Hits        230418   284910    +54492     
+ Misses      115230    62317    -52913     
  Partials         8        8               

Files with missing lines	Coverage Δ
stackslib/src/net/api/liststackerdbreplicas.rs	90.00% <100.00%> (ø)

... and 432 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c76743e...e858b09. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[wileyj]

with the composite merged and working, i think this one is also ready to go