add openrpc links

nervosnetwork · Oct 12, 2023 · 6b0500e · 6b0500e
1 parent 85116d9
commit 6b0500e
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 62 deletions.
diff --git a/devtools/doc/rpc-gen/src/gen.rs b/devtools/doc/rpc-gen/src/gen.rs
@@ -14,9 +14,10 @@ impl RpcModule {
         let mut res = String::new();
         let capitlized = self.module_title.to_string();
         res.push_str(&format!(
-            "    * [Module {}](#module-{})\n",
+            "    * [Module {}](#module-{}) {}\n",
             capitlized,
-            self.module_title.to_lowercase()
+            self.module_title.to_lowercase(),
+            gen_module_openrpc_playground(&capitlized)
         ));
         let mut method_names = self
             .module_methods
@@ -42,6 +43,10 @@ impl RpcModule {
         let description = self.module_description.replace("##", "#####");
 
         res.push_str(&format!("### Module {}\n", capitlized));
+        res.push_str(&format!(
+            "- {}\n\n",
+            gen_module_openrpc_playground(&capitlized)
+        ));
         res.push_str(&format!("{}\n\n", description));
 
         for method in &self.module_methods {
@@ -77,7 +82,7 @@ impl RpcModule {
                 name, signatures, desc,
             ));
         }
-        res
+        res + "\n"
     }
 }
 
@@ -165,13 +170,13 @@ impl RpcDocGenerator {
 
         // generate module methods content
         for rpc_module in self.rpc_module_methods.iter() {
-            let content = format!("{}\n", rpc_module.gen_module_content());
-            res.push_str(&content);
+            if rpc_module.module_title == "Subscription" {
+                gen_subscription_rpc_doc(&mut res);
+            } else {
+                res.push_str(&rpc_module.gen_module_content());
+            }
         }
 
-        // generate subscription module
-        gen_subscription_rpc_doc(&mut res);
-
         // generate type content
         res.push_str("## RPC Types\n");
         self.gen_type_content(&mut res);
@@ -404,6 +409,19 @@ fn gen_subscription_rpc_doc(res: &mut String) {
     res.push_str(format!("{}\n", sub_desc).as_str());
 }
 
+/// generate openrpc playground urls
+fn gen_module_openrpc_playground(module: &str) -> String {
+    let logo = "https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg";
+    let title = format!("CKB-{}", capitlize(module));
+    let json_url = format!(
+        "https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/{}_rpc_doc.json",
+        module.to_lowercase()
+    );
+
+    format!("[👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]={}&uiSchema[appBar][ui:splitView]=false", title) +
+    format!("&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]={}&schemaUrl={})", logo, json_url).as_str()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

diff --git a/rpc/README.md b/rpc/README.md
@@ -31,9 +31,9 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
 
 
 * [RPC Methods](#rpc-methods)
-    * [Module Alert](#module-alert)
+    * [Module Alert](#module-alert) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Alert&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/alert_rpc_doc.json)
         * [Method `send_alert`](#method-send_alert)
-    * [Module Chain](#module-chain)
+    * [Module Chain](#module-chain) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Chain&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/chain_rpc_doc.json)
         * [Method `get_block`](#method-get_block)
         * [Method `get_block_by_number`](#method-get_block_by_number)
         * [Method `get_header`](#method-get_header)
@@ -57,30 +57,30 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
         * [Method `estimate_cycles`](#method-estimate_cycles)
         * [Method `get_fee_rate_statics`](#method-get_fee_rate_statics)
         * [Method `get_fee_rate_statistics`](#method-get_fee_rate_statistics)
-    * [Module Debug](#module-debug)
+    * [Module Debug](#module-debug) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Debug&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/debug_rpc_doc.json)
         * [Method `jemalloc_profiling_dump`](#method-jemalloc_profiling_dump)
         * [Method `update_main_logger`](#method-update_main_logger)
         * [Method `set_extra_logger`](#method-set_extra_logger)
-    * [Module Experiment](#module-experiment)
+    * [Module Experiment](#module-experiment) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Experiment&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/experiment_rpc_doc.json)
         * [Method `dry_run_transaction`](#method-dry_run_transaction)
         * [Method `calculate_dao_maximum_withdraw`](#method-calculate_dao_maximum_withdraw)
-    * [Module Indexer](#module-indexer)
+    * [Module Indexer](#module-indexer) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Indexer&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/indexer_rpc_doc.json)
         * [Method `get_indexer_tip`](#method-get_indexer_tip)
         * [Method `get_cells`](#method-get_cells)
         * [Method `get_transactions`](#method-get_transactions)
         * [Method `get_cells_capacity`](#method-get_cells_capacity)
-    * [Module Integration_test](#module-integration_test)
+    * [Module Integration_test](#module-integration_test) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Integration_test&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/integration_test_rpc_doc.json)
         * [Method `process_block_without_verify`](#method-process_block_without_verify)
         * [Method `truncate`](#method-truncate)
         * [Method `generate_block`](#method-generate_block)
         * [Method `generate_epochs`](#method-generate_epochs)
         * [Method `notify_transaction`](#method-notify_transaction)
         * [Method `generate_block_with_template`](#method-generate_block_with_template)
         * [Method `calculate_dao_field`](#method-calculate_dao_field)
-    * [Module Miner](#module-miner)
+    * [Module Miner](#module-miner) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Miner&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/miner_rpc_doc.json)
         * [Method `get_block_template`](#method-get_block_template)
         * [Method `submit_block`](#method-submit_block)
-    * [Module Net](#module-net)
+    * [Module Net](#module-net) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Net&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/net_rpc_doc.json)
         * [Method `local_node_info`](#method-local_node_info)
         * [Method `get_peers`](#method-get_peers)
         * [Method `get_banned_addresses`](#method-get_banned_addresses)
@@ -91,17 +91,17 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
         * [Method `add_node`](#method-add_node)
         * [Method `remove_node`](#method-remove_node)
         * [Method `ping_peers`](#method-ping_peers)
-    * [Module Pool](#module-pool)
+    * [Module Pool](#module-pool) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Pool&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/pool_rpc_doc.json)
         * [Method `send_transaction`](#method-send_transaction)
         * [Method `remove_transaction`](#method-remove_transaction)
         * [Method `tx_pool_info`](#method-tx_pool_info)
         * [Method `clear_tx_pool`](#method-clear_tx_pool)
         * [Method `get_raw_tx_pool`](#method-get_raw_tx_pool)
         * [Method `tx_pool_ready`](#method-tx_pool_ready)
-    * [Module Stats](#module-stats)
+    * [Module Stats](#module-stats) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Stats&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/stats_rpc_doc.json)
         * [Method `get_blockchain_info`](#method-get_blockchain_info)
         * [Method `get_deployments_info`](#method-get_deployments_info)
-    * [Module Subscription](#module-subscription)
+    * [Module Subscription](#module-subscription) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Subscription&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/subscription_rpc_doc.json)
         * [Method `subscribe`](#method-subscribe)
         * [Method `unsubscribe`](#method-unsubscribe)
 * [RPC Types](#rpc-types)
@@ -200,6 +200,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
     * [Type `UncleTemplate`](#type-uncletemplate)
 * [RPC Errors](#rpc-errors)
 ### Module Alert
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Alert&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/alert_rpc_doc.json)
+
 RPC Module Alert for network alerts.
 
 An alert is a message about critical problems to be broadcast to all nodes via the p2p network.
@@ -263,6 +265,8 @@ Response
 ```
 
 ### Module Chain
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Chain&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/chain_rpc_doc.json)
+
 RPC Module Chain for methods related to the canonical chain.
 
 This module queries information about the canonical chain.
@@ -1854,6 +1858,8 @@ Response
 ```
 
 ### Module Debug
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Debug&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/debug_rpc_doc.json)
+
 RPC Module Debug for internal RPC methods.
 
 **This module is for CKB developers and will not guarantee compatibility.** The methods here
@@ -1893,6 +1899,8 @@ they only append logs to their log files.
 Removes the logger when this is null.
 
 ### Module Experiment
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Experiment&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/experiment_rpc_doc.json)
+
 RPC Module Experiment for experimenting methods.
 
 **EXPERIMENTAL warning**
@@ -2042,6 +2050,8 @@ Response
 ```
 
 ### Module Indexer
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Indexer&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/indexer_rpc_doc.json)
+
 RPC Module Indexer.
 
 #### Method `get_indexer_tip`
@@ -2902,6 +2912,8 @@ Response
 ```
 
 ### Module Integration_test
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Integration_test&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/integration_test_rpc_doc.json)
+
 RPC for Integration Test.
 
 #### Method `process_block_without_verify`
@@ -3394,6 +3406,8 @@ Response
 ```
 
 ### Module Miner
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Miner&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/miner_rpc_doc.json)
+
 RPC Module Miner for miners.
 
 A miner gets a template from CKB, optionally selects transactions, resolves the PoW puzzle, and
@@ -3605,6 +3619,8 @@ Response
 ```
 
 ### Module Net
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Net&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/net_rpc_doc.json)
+
 RPC Module Net for P2P network.
 
 #### Method `local_node_info`
@@ -4141,6 +4157,8 @@ Response
 ```
 
 ### Module Pool
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Pool&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/pool_rpc_doc.json)
+
 RPC Module Pool for transaction memory pool.
 
 #### Method `send_transaction`
@@ -4421,6 +4439,8 @@ Response
 ```
 
 ### Module Stats
+- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Stats&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/stats_rpc_doc.json)
+
 RPC Module Stats for getting various statistic data.
 
 #### Method `get_blockchain_info`
@@ -4514,50 +4534,11 @@ Response
 }
 ```
 
-### Module Subscription
- RPC Module Subscription that CKB node will push new messages to subscribers.
-
- RPC subscriptions require a full duplex connection. CKB offers such connections in the form of
- TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with
- rpc.ws_listen_address).
-
- ############### Examples
-
- TCP RPC subscription:
-
- ```bash
- telnet localhost 18114
- > {"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]}
- < {"jsonrpc":"2.0","result":"0x0","id":2}
- < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...",
-"subscription":0}}
- < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...",
-"subscription":0}}
- < ...
- > {"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}
- < {"jsonrpc":"2.0","result":true,"id":2}
- ```
-
- WebSocket RPC subscription:
-
- ```javascript
- let socket = new WebSocket("ws://localhost:28114")
-
- socket.onmessage = function(event) {
-   console.log(`Data received from server: ${event.data}`);
- }
-
- socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]}`)
-
- socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}`)
- ```
-
-
 RPC Module Subscription that CKB node will push new messages to subscribers.
 
 RPC subscriptions require a full duplex connection. CKB offers such connections in the form of
-TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with
-rpc.ws_listen_address).
+TCP (enable with `rpc.tcp_listen_address` configuration option) and WebSocket (enable with
+`rpc.ws_listen_address`).
 
 ###### Examples
 

diff --git a/rpc/src/module/subscription.rs b/rpc/src/module/subscription.rs
@@ -10,8 +10,8 @@ use tokio::sync::broadcast;
 /// RPC Module Subscription that CKB node will push new messages to subscribers.
 ///
 /// RPC subscriptions require a full duplex connection. CKB offers such connections in the form of
-/// TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with
-/// rpc.ws_listen_address).
+/// TCP (enable with `rpc.tcp_listen_address` configuration option) and WebSocket (enable with
+/// `rpc.ws_listen_address`).
 ///
 /// ###### Examples
 ///