The RPC reference documentation is imperfectly duplicated

The Octez RPCs are currently documented in two places:

1. The RPC references generated by our custom tool doc_gen/rpc_doc.ml: https://tezos.gitlab.io/shell/rpc.html

• one page for shell RPCs + N pages for protocol-specific RPCs (cross-linked together)

2. Browsable JSON OpenAPI specifications: https://tezos.gitlab.io/api/openapi.html

• one spec for shell RPCs + N specs for protocol-specific RPCs + N specs for protocol-specific mempool RPCs

Each of these two references has some lacks (-) and bonuses (+). In particular:

• RPC ref
  • (-) lacks some RPCS (e.g. GET /pending_operations, GET ../helpers/baking_rights)
  • (+) describes input & output parameters (part of the query) in binary form
  • (+) differentiates some query parameters with no value (e.g. async & force in POST /injection/block?[async]&[force]&[chain=<chain_id>])
  • (-) sometimes doesn't list query parameters in the path (e.g. PATCH /network/points/<point>)
  • (+) describes a more detailed type for some optional query parameters (e.g. filter in GET /network/points?(filter=<p2p.point.state_filter>)*)
• Openapi
  • (+) describes the parameters which are parts of the path
  • (+) sometimes contains one more comment on some arguments (e.g. "A date in seconds from epoch" on min_date in GET /chains/<chain_id>/blocks)
  • (+) describes the "default" response (i.e. the error response)
  • (-) the description of some request bodies is sometimes included as a field called "description", instead of as a comment (e.g. POST /injection/protocol)

Differences have also been reported on the protocol-specific RPCs, for Jakarata (in a discussion on a slack private channel https://tezos-dev.slack.com/archives/G01CGLUKKU0/p1661336352767159):

The thing with the open API is that I feel like there are missing or extra properties. [...] example for "header" in a block response: The doc says there is a "content" required, but if I look at an example for the chain, there is no such property. The doc doesn't mention the properties "payload_hash", "payload_round", "proof_of_work_nonce", "liquidity_baking_toggle_vote" but they are present in the example from the chain. I see other discrepancies which make it hard to use. If I remember correctly the other doc was more precise.

However, this seems to be just a display problem, because these fields can be found by looking into the raw Json Openapi description in the schema 014-PtKathma.block_header.alpha.full_header.

This imperfect duplication should be solved by providing the union of information of the two reference docs.

For instance, by adding the missing information in the OpenAPI specs vs the RPC reference.