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 76.31579% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.46%. Comparing base (bc00b29) to head (84d7624).

Files with missing lines	Patch %	Lines
stackslib/src/net/httpcore.rs	74.03%	27 Missing ⚠️
stackslib/src/net/http/error.rs	68.75%	10 Missing ⚠️
stackslib/src/net/tests/httpcore.rs	89.13%	5 Missing ⚠️
stackslib/src/net/http/mod.rs	40.00%	3 Missing ⚠️

❌ Your project check has failed because the head coverage (77.46%) 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    67.63%   77.46%   +9.82%     
===========================================
  Files          586      586              
  Lines       362403   362564     +161     
===========================================
+ Hits        245099   280844   +35745     
+ Misses      117304    81720   -35584     

Files with missing lines	Coverage Δ
stackslib/src/config/mod.rs	68.24% <ø> (+5.86%)	⬆️
stackslib/src/net/http/request.rs	82.69% <100.00%> (+1.33%)	⬆️
stackslib/src/net/http/mod.rs	51.45% <40.00%> (-0.59%)	⬇️
stackslib/src/net/tests/httpcore.rs	97.22% <89.13%> (+15.30%)	⬆️
stackslib/src/net/http/error.rs	56.41% <68.75%> (+5.28%)	⬆️
stackslib/src/net/httpcore.rs	81.84% <74.03%> (+0.39%)	⬆️

... and 308 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 bc00b29...84d7624. 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 👍

[brice-stacks]

This looks good to me! I just had one small request that might help with clarity.

[brice-stacks]

While you're making changes, maybe we could rename this to deployer_address. contract_address sounds like it should include the contract name, so the fact that it is just the deployer address is a bit surprising.

[simone-stacks]

Done in b06eb08, I also changed some comments in docs/event-dispatcher.md - Is this ok?

[simone-stacks]

I just added a small test for the 405 addition in 84d7624 and added 405 in some previous tests @jacinta-stacks @brice-stacks