add CI checks for changes on monitoring APIs

[GitGab19]

In #450 we are changing the schema on one monitoring endpoint (/api/v1/server/channels), and this could lead to some adaptations needed on the sv2-ui project as a consequence (as pointed out in this comment).

We need some CI checks for this kind of issues, we cannot rely entirely on humans, since it's very easy to forget about it.

A couple of months ago I started to discuss this with @lucasbalieiro, and I remember something about using the API schema to validate changes on a PR.

[lucasbalieiro]

Ok, I'll think of something

[plebhash]

let's also add a new section to CONTRIBUTING.md with the guidelines established on the Monitoring API Strategy section of this comment: stratum-mining/sv2-ui#116 (comment)

[lucasbalieiro]

I created a small CLI tool that generates openapi.json, so we can run it directly in CI instead of spinning up a web server and fetching it via curl.

cargo run --bin generate-openapi --features monitoring > src/monitoring/openapi.json

Proposed workflow:

• Generate the initial openapi.json and commit it to the repository.
• In CI, regenerate openapi.json for each PR and compare it against main.
• If there’s any diff, fail the CI check to signal that openapi.json needs to be updated.

We could automate updating the committed file, but during the dev call we agreed to be more deliberate about monitoring API changes, especially breaking ones. This approach enforces that discipline by making changes explicit in the diff.

Once this validation is in place, we could later extend the flow: after a PR is merged, trigger an event in the sv2-ui repo to open an issue referencing the API change. I’d prefer to handle that in a separate PR, since the exact integration on the sv2-ui side is still unclear.

What do you guys think?

[plebhash]

I created a small CLI tool that generates openapi.json

where is it? how does it work?

We could automate updating the committed file, but during the dev call we agreed to be more deliberate about monitoring API changes, especially breaking ones.

yeah I guess that would defeat the purpose

[lucasbalieiro]

Oh, it is right here: lucasbalieiro@f7b36f1

If you checkout the branch, just go inside the stratum-apps and run: cargo run --bin generate-openapi --features monitoring > src/monitoring/openapi.json

This will generate/replace the current openapi.json commited.

Since the docs of utoipa says that it generates this json at compile time, I just created this bin to leverage this. Instead of curling the json at runtime when the http server is up

[lucasbalieiro]

also thinking about the sv2-ui side:

the safest approach, I think, is to automagically open an issue there whenever the monitoring API changes. While we could automate updates on the server side, that wouldn’t fully solve the problem, frontend changes still require manual decisions.

For example, if fields are added or removed, we can regenerate the server schema automatically, but we still need to decide how those changes should be handled in the UI. Automating that part would be risky and could easily lead to inconsistencies or broken behavior.

To keep changes visible and actionable, we could file an issue like:

“sv2-apps updated the monitoring API in PR #XX.”

From there, we can review the changes and decide how to adapt the frontend accordingly.

[GitGab19]

Completely agree with your approach @lucasbalieiro, looking forward to seeing your PR.