From 7a1ee66763d8e4dee19cb59cf81edb1043604ae2 Mon Sep 17 00:00:00 2001
From: Anton Kaliaev <anton.kalyaev@gmail.com>
Date: Thu, 25 Jun 2020 09:53:18 +0400
Subject: [PATCH] rpc: move docs from doc.go to swagger.yaml (#5044)

also,

- add an example for WS
- mention that a subscription could be terminated in /subscribe

Closes #5014
---
 rpc/core/doc.go          | 75 ++--------------------------------------
 rpc/swagger/swagger.yaml | 53 ++++++++++++++++++++++++++--
 2 files changed, 54 insertions(+), 74 deletions(-)

diff --git a/rpc/core/doc.go b/rpc/core/doc.go
index a51a02982..b68231725 100644
--- a/rpc/core/doc.go
+++ b/rpc/core/doc.go
@@ -1,75 +1,8 @@
 /*
-# Introduction
+Package core defines the Tendermint RPC endpoints.
 
-Tendermint supports the following RPC protocols:
-
-* URI over HTTP
-* JSONRPC over HTTP
-* JSONRPC over websockets
-
-Tendermint RPC is built using our own RPC library which contains its own set of documentation and tests.
-See it here: https://github.com/tendermint/tendermint/tree/master/rpc/lib
-
-## Configuration
-
-RPC can be configured by tuning parameters under `[rpc]` table in the `$TMHOME/config/config.toml` file
-or by using the `--rpc.X` command-line flags.
-
-Default rpc listen address is `tcp://0.0.0.0:26657`.
-To set another address, set the `laddr` config parameter to desired value.
-CORS (Cross-Origin Resource Sharing) can be enabled by setting
-`cors_allowed_origins`, `cors_allowed_methods`, `cors_allowed_headers` config parameters.
-
-## Arguments
-
-Arguments which expect strings or byte arrays may be passed as quoted strings,
-like `"abc"` or as `0x`-prefixed strings, like `0x616263`.
-
-## URI/HTTP
-
-```bash
-curl 'localhost:26657/broadcast_tx_sync?tx="abc"'
-```
-
-> Response:
-
-```json
-{
-	"error": "",
-	"result": {
-		"hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
-		"log": "",
-		"data": "",
-		"code": "0"
-	},
-	"id": "",
-	"jsonrpc": "2.0"
-}
-```
-
-## JSONRPC/HTTP
-
-JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g. `http://localhost:26657/`).
-
-```json
-{
-	"method": "broadcast_tx_sync",
-	"jsonrpc": "2.0",
-	"params": [ "abc" ],
-	"id": "dontcare"
-}
-```
-
-## JSONRPC/websockets
-
-JSONRPC requests can be made via websocket.
-The websocket endpoint is at `/websocket`, e.g. `localhost:26657/websocket`.
-Asynchronous RPC functions like event `subscribe` and `unsubscribe` are only available via websockets.
-
-
-## More Examples
-
-See the various bash tests using curl in `test/`, and examples using the `Go` API in `rpc/client/`.
+Tendermint ships with its own JSONRPC library -
+https://github.com/tendermint/tendermint/tree/master/rpc/jsonrpc.
 
 ## Get the list
 
@@ -111,7 +44,5 @@ Endpoints that require arguments:
 /unsafe_write_heap_profile?filename=_
 /unsubscribe?event=_
 ```
-
-# Endpoints
 */
 package core
diff --git a/rpc/swagger/swagger.yaml b/rpc/swagger/swagger.yaml
index b7c74b8e9..1d4e23e2d 100644
--- a/rpc/swagger/swagger.yaml
+++ b/rpc/swagger/swagger.yaml
@@ -1,7 +1,53 @@
 openapi: 3.0.0
 info:
-  title: RPC client for Tendermint
-  description: A REST interface for state queries, transaction generation and broadcasting.
+  title: Tendermint RPC
+  description: |
+    Tendermint supports the following RPC protocols:
+
+    * URI over HTTP
+    * JSONRPC over HTTP
+    * JSONRPC over websockets
+
+    ## Configuration
+
+    RPC can be configured by tuning parameters under `[rpc]` table in the
+    `$TMHOME/config/config.toml` file or by using the `--rpc.X` command-line
+    flags.
+
+    Default rpc listen address is `tcp://0.0.0.0:26657`.
+    To set another address, set the `laddr` config parameter to desired value.
+    CORS (Cross-Origin Resource Sharing) can be enabled by setting
+    `cors_allowed_origins`, `cors_allowed_methods`, `cors_allowed_headers`
+    config parameters.
+
+    ## Arguments
+
+    Arguments which expect strings or byte arrays may be passed as quoted
+    strings, like `"abc"` or as `0x`-prefixed strings, like `0x616263`.
+
+    ## URI/HTTP
+
+    A REST like interface.
+
+        curl localhost:26657/block?height=5
+
+    ## JSONRPC/HTTP
+
+    JSONRPC requests can be POST'd to the root RPC endpoint via HTTP.
+
+        curl --header "Content-Type: application/json" --request POST --data '{"method": "block", "params": ["5"], "id": 1}' localhost:26657
+
+    ## JSONRPC/websockets
+
+    JSONRPC requests can be also made via websocket.
+    The websocket endpoint is at `/websocket`, e.g. `localhost:26657/websocket`.
+    Asynchronous RPC functions like event `subscribe` and `unsubscribe` are
+    only available via websockets.
+
+    Example using https://github.com/hashrocket/ws:
+
+        ws ws://localhost:26657/websocket
+        > { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlock'"], "id": 1 }
   version: "Master"
   license:
     name: Apache 2.0
@@ -309,6 +355,9 @@ paths:
            }
         }()
         ```
+
+        NOTE: if you're not reading events fast enough, Tendermint might
+        terminate the subscription.
       parameters:
         - in: query
           name: query