search

casper-network / docs

Application running the documentation markdown files.
Apache License 2.0
25 stars 65 forks source link

Host and display the JSON-RPC schema in an easier to read format - Testnet #314

Closed devendran-m closed 1 year ago

devendran-m commented 2 years ago

Request:

We can currently query the node: http://65.21.235.219:8888/rpc-schema. Or use the Casper client subcommand list-rpcs. MAKE created this URL for the previous version (1.0.0): http://casper-rpc-docs.s3-website-us-east-1.amazonaws.com/. Please help create a similar link for the Testnet

Component: JSON-RPC Assignee: SRE team cc: @sacherjj @bradjohnl

ipopescu commented 2 years ago

@devendran-m can you please discuss this with the SRE team?

RitaMAllenCA commented 1 year ago

@sacherjj @bradjohnl Should this be in the SRE repo? Doesn't look like a docs issue

sacherjj commented 1 year ago

Rendering would only need to be done as part of a node release and eventually rpc sidecar release. But it should live on the docs site.

bradjohnl commented 1 year ago

After testing and analysis, I have concluded, also thanks to @andrzej-casper help, that it is currently not possible to render the OpenRPC API definition inside the JSONRPC documentation that gets produced by calling the casper-client list-rpcs function, using the OpenRPC provided libraries and tooling.

The main reason for that is due to a combinations of 2 things:

I can provide more information with specific examples if needed, but for the sake of clarity, I am omitting them in this comment.

How do we move forward heavily depends on how much time and effort we want to dedicate on making this work.

  1. Dive deeper into the libraries involved in the bug above, and submit a PR to fix the bug.
  2. Create our own generator that loops through the JSON spec and generates the pretty documentation as html.
  3. Try to implement proper referencing in the generated documentation so that circular references are eliminated or replaced with other constructs.

It's currently very hard to estimate the effort necessary for each course of action. TBH I think the option N.1 is probably the quickest, followed by a close battle between 2. and 3. As the documentation is very long and complex, it might be an equally sizable effort to untangle it compared to creating our own pretty renderer.

@sacherjj @devendran-m @RitaMAllenCA

RitaMAllenCA commented 1 year ago

Moving this to the 2.0 timeframe for further consideration. We will organically be making updates to the RPC client and perhaps as part of that work we can reconsider this.

ACStone-MTS commented 1 year ago

Closing this ticket and #313 based on the discussions here in and the fact that we host the JSON-RPC API in its entirety on the docs site.