feat: openapi spec cleanup for schemathesis fuzzing and cleaner API error responses

[simone-stacks]

Description

Improves OpenAPI schema definitions for better API documentation accuracy and validation.

Also introduces proper 405/404/400 HTTP error responses with allow headers.

These changes improve schema accuracy for tools like Schemathesis and ensure the OpenAPI spec matches actual API behavior.

A summary of the findings can be found here.

Applicable issues

• Fixes https://github.com/stx-labs/core-epics/issues/75

Additional info (benefits, drawbacks, caveats)

Benefits:

• More accurate API documentation
• Better client code generation from OpenAPI spec
• Enables automated API testing with Schemathesis
• Clearer error responses for API consumers:
  • 400 for invalid path parameters (e.g. /v3/blocks/NOTAHEX) - previously returned 404
  • 404 for paths that don't exist
  • 405 with Allow header for wrong HTTP methods - helps clients discover correct methods
• The 400 approach tells consumers "you found the right endpoint, fix your parameter" rather than "this doesn't exist"

Caveats:

• Stricter schemas may flag previously "working" requests that were technically invalid
• Some endpoints with complex parameter patterns (contract names, principals) still return 404 for invalid params instead of 400 - this matches previous behavior

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

[codecov]

Codecov Report

❌ Patch coverage is 47.91667% with 75 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.45%. Comparing base (e156f8d) to head (efb8fc8).

Files with missing lines	Patch %	Lines
stackslib/src/net/httpcore.rs	63.46%	38 Missing ⚠️
stackslib/src/net/http/error.rs	0.00%	32 Missing ⚠️
stackslib/src/net/http/mod.rs	0.00%	5 Missing ⚠️

❌ Your project check has failed because the head coverage (71.45%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6756      +/-   ##
===========================================
+ Coverage    68.57%   71.45%   +2.87%     
===========================================
  Files          582      582              
  Lines       361458   361573     +115     
===========================================
+ Hits        247879   258348   +10469     
+ Misses      113579   103225   -10354     

Files with missing lines	Coverage Δ
stackslib/src/net/http/request.rs	81.97% <100.00%> (-0.12%)	⬇️
stackslib/src/net/http/mod.rs	49.51% <0.00%> (-2.53%)	⬇️
stackslib/src/net/http/error.rs	34.12% <0.00%> (-8.69%)	⬇️
stackslib/src/net/httpcore.rs	80.40% <63.46%> (-1.91%)	⬇️

... and 379 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 e156f8d...efb8fc8. 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.

[BowTiedRadone]

@simone-stacks Thanks for opening the PR! I've just wrapped up an initial review focused on the specification changes. More reviews to come, as I am trying to check them carefully and ensure we maximize the impact of this effort.

[BowTiedRadone]

This PR is in a great spot now! After checking the last two suggestions I left, I believe it's ready to be taken out of draft and get some more eyes on it.

[BowTiedRadone]

Checked again, this looks ready for reviews from reviewers with write access 👍