[DOC] Undocumented RPC endpoints

[telezhnaya]

Here, we have a number of undocumented RPC endpoints. + and nickname near the method means this person agreed to cover it with the doc.

• health
• light_client_proof - @posvyatokum
• network_routes - @saketh-are
• next_light_client_block
• tier1_network_info - @saketh-are
• EXPERIMENTAL_broadcast_tx_sync
• EXPERIMENTAL_check_tx
• EXPERIMENTAL_light_client_proof - @posvyatokum
• EXPERIMENTAL_validators_ordered
• EXPERIMENTAL_maintenance_windows
• EXPERIMENTAL_split_storage_info
• query:
  • view_state
  • include_proof flag

@bowenwang1996 @ailisp @mina86 @saketh-are, please tag the other authors as well

[telezhnaya]

Also, the flag include_proof was never documented
https://docs.near.org/api/rpc/contracts
Added by this PR
cc @mina86

[mina86]

near/nearcore#7714

Also, the whole proof infrastructure is still work in progress so I’d argue it’s not that high priority.

[saketh-are]

I'll send a PR documenting tier1_network_info.

We also recently added network_routes (it was merged in near/nearcore#9330 after this issue was created). I will document that one as well.

[bucanero]

On a side note, I think it would be super helpful for future docs, if we could auto-generate some OpenAPI reference out of the RPC node source code.
Pagoda did that for the Enhanced API, and creating /updating docs could be done quickly with any tool that turns OpenAPI json/yaml files into documentation.

[telezhnaya]

@bucanero it's impossible, unfortunately, because OpenAPI does not support JSON RPC
OAI/OpenAPI-Specification#801

[bucanero]

Oh, I see, thanks for the feedback @telezhnaya .

I was reviewing a bit about JSON-RPC, and it seems a good option could be https://open-rpc.org/ . It's a fork of openApi, modified to accommodate JSON-RPC APIs.

Perhaps we can consider this as an alternative to find a way to auto-generate good docs for our node API

[telezhnaya]

I feel it's too raw and I'm not ready to invest much time. There's only one Rust crate I've found https://lib.rs/crates/openrpc, version 0.1.0 does not sound promising to me
I think the best we can do here right now is just to suffer and wait, trying to document methods while we remember about it