feat(rpc): OpenAPI spec

[oxarbitrage]

Motivation

As part of the hackaton sprint i went over developing a swagger API for zebra RPC methods. I tried different rust tools initially but they didn't went too well so i decided to create an utility that can extract the information needed from the documentation in the Rust code and create a specification with that.

The result of that is in this PR, it is a bit fragile and needs some more work but i think is a good start.

PR Author Checklist

Check before marking the PR as ready for review:

• Will the PR name make sense to users?
• Does the PR have a priority label?
• Have you added or updated tests?
• Is the documentation up to date?

Solution

The generator will scrape data from the rust docs files to get the information needed to generate the open api spec. This code is a bit fragile and can be improved. This results in a binary called openapi-generator in the zebra-utils crate.

There is a lot of changes to method documentations to make them fit in the needed format, i tried to not make it very different than what we already had.

There are some defaults added to types so we can show example responses.

Testing

Manually. You can run the generator and paste the output into https://editor.swagger.io/

Review

Anyone can review.

Reviewer Checklist

Check before approving the PR:

• Does the PR scope match the ticket?
• Are there enough tests to make sure it works? Do the tests cover the PR motivation?
• Are all the PR blockers dealt with?
  PR blockers can be dealt with in new tickets or PRs.

And check the PR Author checklist is complete.

Follow Up Work

• There are some TODOs in the code.
• The gRPC methods from the scanner are not included. For these the documentation is in the proto files and there are some tools to transform that to an openapi spec, so it should be a matter of adding that command at the end of the script and append the output.

[gustavovalverde]

This is lovely! ❤️

[upbqdn]

Amazing. A great foundation for #8324.

[upbqdn]

Also, thanks for the thorough comments describing the parsing process.