From b7aef5c8b4fc5e6efd46fe9e48b618f208353edb Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 21 Apr 2022 23:02:26 +0200 Subject: [PATCH] feat: rpc-api deprecated|experimental|.. states (#1086) Leverages Status field from https://github.com/ipfs/go-ipfs-cmds/pull/225 https://github.com/ipfs/go-ipfs/pull/8802 and uses that information while generating HTTP RPC API reference docs. --- docs/reference/http/api.md | 306 +++++++++++----------- tools/http-api-docs/endpoints.go | 12 + tools/http-api-docs/formatter.go | 29 +- tools/http-api-docs/go.mod | 6 +- tools/http-api-docs/go.sum | 10 +- tools/http-api-docs/http-api-docs/main.go | 3 +- tools/http-api-docs/markdown.go | 66 ++++- 7 files changed, 260 insertions(+), 172 deletions(-) diff --git a/docs/reference/http/api.md b/docs/reference/http/api.md index 03e5689c4..9c20c03a4 100644 --- a/docs/reference/http/api.md +++ b/docs/reference/http/api.md @@ -48,7 +48,7 @@ I AM SERIOUS, DO NOT EDIT ANYTHING BELOW ;-D --> -::: tip Generated on 2022-02-19, from go-ipfs v0.12.0 +::: tip Generated on 2022-04-21, from go-ipfs v0.12.2 This document was autogenerated. For issues and support, check out the [http-api-docs](https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs) generator on GitHub. ::: @@ -61,7 +61,7 @@ In many cases, using this RPC API is preferable to embedding IPFS directly in yo The RPC API provides admin-level access to your IPFS node, including `/api/v0/config`. -It is bound to `localhost` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service. +It is bound to `localhost` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service. If you are looking for an interface designed for browsers and public internet, consider [Gateway](/concepts/glossary/#gateway) instead. ::: @@ -162,13 +162,17 @@ A `405` error may mean that you are using the wrong HTTP method (i.e. GET instea When a request is sent from a browser, HTTP RPC API follows the [Origin-based security model](https://en.wikipedia.org/wiki/Same-origin_policy), and expects the `Origin` HTTP header to be present. The API will return HTTP Error 403 when Origin is missing, does not match the API port, or is not safelisted via `API.HTTPHeaders.Access-Control-Allow-Origin` in the config. -## HTTP RPC commands + +## RPC commands + + + + ## /api/v0/add Add a file or directory to IPFS. - ### Arguments @@ -242,11 +246,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bitswap/ledger Show the current ledger for a peer. - ### Arguments - `arg` [string]: The PeerID (B58) of the ledger to inspect. Required: **yes**. @@ -273,11 +277,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bitswap/reprovide Trigger reprovider. - ### Arguments This endpoint takes no arguments. @@ -297,11 +301,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/bitswap/stat Show some diagnostic information on the bitswap agent. - ### Arguments - `verbose` [bool]: Print extra information. Required: no. @@ -340,11 +344,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bitswap/wantlist Show blocks currently on the wantlist. - ### Arguments - `peer` [string]: Specify which peer to show wantlist for. Required: no. @@ -371,11 +375,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/block/get Get a raw IPFS block. - ### Arguments - `arg` [string]: The base58 multihash of an existing block to get. Required: **yes**. @@ -395,11 +399,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/block/put Store input as an IPFS block. - ### Arguments @@ -432,11 +436,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/block/rm Remove IPFS block(s). - ### Arguments - `arg` [string]: Bash58 encoded multihash of block(s) to remove. Required: **yes**. @@ -462,11 +466,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/block/stat Print information of a raw IPFS block. - ### Arguments - `arg` [string]: The base58 multihash of an existing block to stat. Required: **yes**. @@ -490,11 +494,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bootstrap Show or edit the list of bootstrap peers. - ### Arguments This endpoint takes no arguments. @@ -519,11 +523,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bootstrap/add Add peers to the bootstrap list. - ### Arguments - `arg` [string]: A peer to add to the bootstrap list (in the format '<multiaddr>/<peerID>') Required: no. @@ -549,11 +553,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bootstrap/add/default Add default peers to the bootstrap list. - ### Arguments This endpoint takes no arguments. @@ -578,11 +582,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bootstrap/list Show peers in the bootstrap list. - ### Arguments This endpoint takes no arguments. @@ -607,11 +611,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bootstrap/rm Remove peers from the bootstrap list. - ### Arguments - `arg` [string]: A peer to add to the bootstrap list (in the format '<multiaddr>/<peerID>') Required: no. @@ -637,11 +641,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/bootstrap/rm/all Remove all peers from the bootstrap list. - ### Arguments This endpoint takes no arguments. @@ -666,11 +670,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/cat Show IPFS object data. - ### Arguments - `arg` [string]: The path to the IPFS object(s) to be outputted. Required: **yes**. @@ -692,11 +696,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/cid/base32 Convert CIDs to Base32 CID version 1. - ### Arguments - `arg` [string]: Cids to convert. Required: **yes**. @@ -721,11 +725,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/cid/bases List available multibase encodings. - ### Arguments - `prefix` [bool]: also include the single letter prefixes in addition to the code. Required: no. @@ -752,11 +756,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/cid/codecs List available CID codecs. - ### Arguments - `numeric` [bool]: also include numeric codes. Required: no. @@ -782,11 +786,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/cid/format Format and convert a CID in various useful ways. - ### Arguments - `arg` [string]: Cids to format. Required: **yes**. @@ -815,11 +819,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/cid/hashes List available multihashes. - ### Arguments - `numeric` [bool]: also include numeric codes. Required: no. @@ -845,11 +849,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/commands List all available commands. - ### Arguments - `flags` [bool]: Show command flags. Required: no. @@ -894,11 +898,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/commands/completion/bash Generate bash shell completions. - ### Arguments This endpoint takes no arguments. @@ -918,11 +922,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/config Get and set IPFS config values. - ### Arguments - `arg` [string]: The key of the config entry (e.g. "Addresses.API"). Required: **yes**. @@ -949,11 +953,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/config/edit Open the config file for editing in $EDITOR. - ### Arguments This endpoint takes no arguments. @@ -973,11 +977,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/config/profile/apply Apply profile to config. - ### Arguments - `arg` [string]: The profile to apply to the config. Required: **yes**. @@ -1006,11 +1010,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/config/replace Replace the config with <file>. - ### Arguments @@ -1035,11 +1039,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/config/show Output config file contents. - ### Arguments This endpoint takes no arguments. @@ -1062,11 +1066,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dag/export Streams the selected DAG as a .car stream on stdout. - ### Arguments - `arg` [string]: CID of a root to recursively export Required: **yes**. @@ -1087,11 +1091,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/dag/get Get a DAG node from IPFS. - ### Arguments - `arg` [string]: The object to get Required: **yes**. @@ -1112,11 +1116,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/dag/import Import the contents of .car files - ### Arguments @@ -1156,11 +1160,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dag/put Add a DAG node to IPFS. - ### Arguments @@ -1194,11 +1198,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dag/resolve Resolve IPLD block. - ### Arguments - `arg` [string]: The path to resolve Required: **yes**. @@ -1224,11 +1228,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dag/stat Gets stats for a DAG. - ### Arguments - `arg` [string]: CID of a DAG root to get statistics for Required: **yes**. @@ -1253,11 +1257,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dht/findpeer Find the multiaddresses associated with a Peer ID. - ### Arguments - `arg` [string]: The ID of the peer to search for. Required: **yes**. @@ -1291,11 +1295,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dht/findprovs Find peers that can provide a specific value, given a key. - ### Arguments - `arg` [string]: The key to find providers for. Required: **yes**. @@ -1330,11 +1334,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dht/get Given a key, query the routing system for its best value. - ### Arguments - `arg` [string]: The key to find a value for. Required: **yes**. @@ -1368,11 +1372,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dht/provide Announce to the network that you are providing given values. - ### Arguments - `arg` [string]: The key[s] to send provide records for. Required: **yes**. @@ -1407,11 +1411,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dht/put Write a key/value pair to the routing system. - ### Arguments - `arg` [string]: The key to store the value at. Required: **yes**. @@ -1451,11 +1455,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/dht/query Find the closest Peer IDs to a given Peer ID by querying the DHT. - ### Arguments - `arg` [string]: The peerID to run the query against. Required: **yes**. @@ -1489,11 +1493,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/diag/cmds List commands run on this IPFS node. - ### Arguments - `verbose` [bool]: Print extra information. Required: no. @@ -1528,11 +1532,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/diag/cmds/clear Clear inactive requests from the log. - ### Arguments This endpoint takes no arguments. @@ -1552,11 +1556,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/diag/cmds/set-time Set how long to keep inactive requests in the log. - ### Arguments - `arg` [string]: Time to keep inactive requests in log. Required: **yes**. @@ -1576,11 +1580,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/diag/profile Collect a performance profile for debugging. - ### Arguments - `output` [string]: The path where the output should be stored. Required: no. @@ -1601,11 +1605,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/diag/sys Print system diagnostic information. - ### Arguments This endpoint takes no arguments. @@ -1625,11 +1629,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/dns Resolve DNS links. - ### Arguments - `arg` [string]: The domain-name name to resolve. Required: **yes**. @@ -1653,11 +1657,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/file/ls List directory contents for Unix filesystem objects. Deprecated: Use 'ipfs ls' instead. - ### Arguments - `arg` [string]: The path to the IPFS object(s) to list links from. Required: **yes**. @@ -1697,11 +1701,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/files/chcid Change the CID version or hash function of the root node of a given path. - ### Arguments - `arg` [string]: Path to change. Default: '/'. Required: no. @@ -1723,11 +1727,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/files/cp Add references to IPFS files and directories in MFS (or copy within MFS). - ### Arguments - `arg` [string]: Source IPFS or MFS path to copy. Required: **yes**. @@ -1749,11 +1753,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/files/flush Flush a given path's data to disk. - ### Arguments - `arg` [string]: Path to flush. Default: '/'. Required: no. @@ -1776,11 +1780,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/files/ls List directories in the local mutable namespace. - ### Arguments - `arg` [string]: Path to show listing for. Defaults to '/'. Required: no. @@ -1812,11 +1816,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/files/mkdir Make directories. - ### Arguments - `arg` [string]: Path to dir to make. Required: **yes**. @@ -1839,11 +1843,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/files/mv Move files. - ### Arguments - `arg` [string]: Source file to move. Required: **yes**. @@ -1864,11 +1868,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/files/read Read a file in a given MFS. - ### Arguments - `arg` [string]: Path to file to be read. Required: **yes**. @@ -1890,11 +1894,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/files/rm Remove a file. - ### Arguments - `arg` [string]: File to remove. Required: **yes**. @@ -1916,11 +1920,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/files/stat Display file status. - ### Arguments - `arg` [string]: Path to node to stat. Required: **yes**. @@ -1966,11 +1970,11 @@ Type: &hash=&size=&with-local="` --- + ## /api/v0/files/write Write to a mutable file in a given filesystem. - ### Arguments - `arg` [string]: Path to write to. Required: **yes**. @@ -2004,11 +2008,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/filestore/dups List blocks that are both in the filestore and standard block storage. - ### Arguments This endpoint takes no arguments. @@ -2032,11 +2036,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/filestore/ls List objects in filestore. - ### Arguments - `arg` [string]: Cid of objects to list. Required: no. @@ -2067,11 +2071,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/filestore/verify Verify objects in filestore. - ### Arguments - `arg` [string]: Cid of objects to verify. Required: no. @@ -2102,11 +2106,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/get Download IPFS objects. - ### Arguments - `arg` [string]: The path to the IPFS object(s) to be outputted. Required: **yes**. @@ -2130,11 +2134,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/id Show IPFS node id info. - ### Arguments - `arg` [string]: Peer.ID of node to look up. Required: no. @@ -2168,11 +2172,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/key/export Export a keypair - ### Arguments - `arg` [string]: name of key to export Required: **yes**. @@ -2193,11 +2197,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/key/gen Create a new keypair - ### Arguments - `arg` [string]: name of key to create Required: **yes**. @@ -2224,11 +2228,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/key/import Import a key and prints imported key id - ### Arguments - `arg` [string]: name to associate with key in keychain Required: **yes**. @@ -2259,11 +2263,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/key/list List all local keypairs. - ### Arguments - `l` [bool]: Show extra information about keys. Required: no. @@ -2292,11 +2296,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/key/rename Rename a keypair. - ### Arguments - `arg` [string]: name of key to rename Required: **yes**. @@ -2325,11 +2329,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/key/rm Remove a keypair. - ### Arguments - `arg` [string]: names of keys to remove Required: **yes**. @@ -2359,11 +2363,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/key/rotate Rotates the IPFS identity. - ### Arguments - `oldkey` [string]: Keystore name to use for backing up your existing identity. Required: no. @@ -2385,11 +2389,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/log/level Change the logging level. - ### Arguments - `arg` [string]: The subsystem logging identifier. Use 'all' for all subsystems. Required: **yes**. @@ -2415,11 +2419,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/log/ls List the logging subsystems. - ### Arguments This endpoint takes no arguments. @@ -2444,11 +2448,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/log/tail Read the event log. - ### Arguments This endpoint takes no arguments. @@ -2468,11 +2472,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/ls List directory contents for Unix filesystem objects. - ### Arguments - `arg` [string]: The path to the IPFS object(s) to list links from. Required: **yes**. @@ -2512,11 +2516,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/mount Mounts IPFS to the filesystem (read-only). - ### Arguments - `ipfs-path` [string]: The path where IPFS should be mounted. Required: no. @@ -2542,11 +2546,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/multibase/decode Decode multibase string - ### Arguments @@ -2571,11 +2575,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/multibase/encode Encode data into multibase string - ### Arguments @@ -2601,11 +2605,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/multibase/list List available multibase encodings. - ### Arguments - `prefix` [bool]: also include the single letter prefixes in addition to the code. Required: no. @@ -2632,11 +2636,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/multibase/transcode Transcode multibase string between bases - ### Arguments @@ -2662,11 +2666,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/name/publish Publish IPNS names. - ### Arguments - `arg` [string]: ipfs path of the object to be published. Required: **yes**. @@ -2699,11 +2703,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/name/pubsub/cancel Cancel a name subscription. - ### Arguments - `arg` [string]: Name to cancel the subscription for. Required: **yes**. @@ -2726,11 +2730,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/name/pubsub/state Query the state of IPNS pubsub. - ### Arguments This endpoint takes no arguments. @@ -2753,11 +2757,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/name/pubsub/subs Show current name subscriptions. - ### Arguments - `ipns-base` [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: `base36`. Required: no. @@ -2782,11 +2786,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/name/resolve Resolve IPNS names. - ### Arguments - `arg` [string]: The IPNS name to resolve. Defaults to your node's peerID. Required: no. @@ -2814,11 +2818,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/data Deprecated way to read the raw bytes of a dag-pb object: use 'dag get' instead. - ### Arguments - `arg` [string]: Key of the object to retrieve, in base58-encoded multihash format. Required: **yes**. @@ -2838,11 +2842,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/object/diff Display the diff between two IPFS objects. - ### Arguments - `arg` [string]: Object to diff against. Required: **yes**. @@ -2878,11 +2882,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/get Deprecated way to get and serialize the dag-pb node. Use 'dag get' instead - ### Arguments - `arg` [string]: Key of the dag-pb object to retrieve, in base58-encoded multihash format. Required: **yes**. @@ -2913,11 +2917,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/links Deprecated way to output links in the specified dag-pb object: use 'dag get' instead. - ### Arguments - `arg` [string]: Key of the dag-pb object to retrieve, in base58-encoded multihash format. Required: **yes**. @@ -2948,11 +2952,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/new Deprecated way to create a new dag-pb object from a template. - ### Arguments - `arg` [string]: Template to use. Optional. Required: no. @@ -2982,11 +2986,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/patch/add-link Deprecated way to add a link to a given dag-pb. - ### Arguments - `arg` [string]: The hash of the node to modify. Required: **yes**. @@ -3019,11 +3023,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/patch/append-data Deprecated way to append data to the data segment of a DAG node. - ### Arguments - `arg` [string]: The hash of the node to modify. Required: **yes**. @@ -3059,11 +3063,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/patch/rm-link Deprecated way to remove a link from dag-pb object. - ### Arguments - `arg` [string]: The hash of the node to modify. Required: **yes**. @@ -3094,11 +3098,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/patch/set-data Deprecated way to set the data field of dag-pb object. - ### Arguments - `arg` [string]: The hash of the node to modify. Required: **yes**. @@ -3134,11 +3138,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/put Deprecated way to store input as a DAG object. Use 'dag put' instead. - ### Arguments @@ -3177,11 +3181,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/object/stat Deprecated way to read stats for the dag-pb node. Use 'files stat' instead. - ### Arguments - `arg` [string]: Key of the object to retrieve, in base58-encoded multihash format. Required: **yes**. @@ -3210,11 +3214,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/p2p/close Stop listening for new connections to forward. - ### Arguments - `all` [bool]: Close all listeners. Required: no. @@ -3238,11 +3242,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/p2p/forward Forward connections to libp2p service. - ### Arguments - `arg` [string]: Protocol name. Required: **yes**. @@ -3265,11 +3269,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/p2p/listen Create libp2p service. - ### Arguments - `arg` [string]: Protocol name. Required: **yes**. @@ -3292,11 +3296,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/p2p/ls List active p2p listeners. - ### Arguments - `headers` [bool]: Print table headers (Protocol, Listen, Target). Required: no. @@ -3325,11 +3329,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/p2p/stream/close Close active p2p stream. - ### Arguments - `arg` [string]: Stream identifier Required: no. @@ -3350,11 +3354,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/p2p/stream/ls List active p2p streams. - ### Arguments - `headers` [bool]: Print table headers (ID, Protocol, Local, Remote). Required: no. @@ -3384,11 +3388,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/add Pin objects to local storage. - ### Arguments - `arg` [string]: Path to object(s) to be pinned. Required: **yes**. @@ -3416,11 +3420,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/ls List objects pinned to local storage. - ### Arguments - `arg` [string]: Path to object(s) to be listed. Required: no. @@ -3456,11 +3460,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/remote/add Pin object to remote pinning service. - ### Arguments - `arg` [string]: Path to object(s) to be pinned. Required: **yes**. @@ -3488,11 +3492,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/remote/ls List objects pinned to remote pinning service. - ### Arguments - `service` [string]: Name of the remote pinning service to use (mandatory). Required: no. @@ -3520,11 +3524,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/remote/rm Remove pins from remote pinning service. - ### Arguments - `service` [string]: Name of the remote pinning service to use (mandatory). Required: no. @@ -3548,11 +3552,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/pin/remote/service/add Add remote pinning service. - ### Arguments - `arg` [string]: Service name. Required: **yes**. @@ -3574,11 +3578,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/pin/remote/service/ls List remote pinning services. - ### Arguments - `stat` [bool]: Try to fetch and display current pin count on remote service (queued/pinning/pinned/failed). Default: `false`. Required: no. @@ -3615,11 +3619,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/remote/service/rm Remove remote pinning service. - ### Arguments - `arg` [string]: Name of remote pinning service to remove. Required: **yes**. @@ -3639,11 +3643,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/pin/rm Remove pinned objects from local storage. - ### Arguments - `arg` [string]: Path to object(s) to be unpinned. Required: **yes**. @@ -3669,11 +3673,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/update Update a recursive pin. - ### Arguments - `arg` [string]: Path to old object. Required: **yes**. @@ -3700,11 +3704,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pin/verify Verify that recursive pins are complete. - ### Arguments - `verbose` [bool]: Also write the hashes of non-broken pins. Required: no. @@ -3737,11 +3741,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/ping Send echo request packets to IPFS hosts. - ### Arguments - `arg` [string]: ID of peer to be pinged. Required: **yes**. @@ -3767,11 +3771,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pubsub/ls List subscribed topics by name. - ### Arguments This endpoint takes no arguments. @@ -3796,11 +3800,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pubsub/peers List peers we are currently pubsubbing with. - ### Arguments - `arg` [string]: Topic to list connected peers of. Required: no. @@ -3825,11 +3829,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/pubsub/pub Publish data to a given pubsub topic. - ### Arguments - `arg` [string]: Topic to publish to. Required: **yes**. @@ -3855,11 +3859,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/pubsub/sub Subscribe to messages on a given topic. - ### Arguments - `arg` [string]: Name of topic to subscribe to. Required: **yes**. @@ -3887,11 +3891,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/refs List links (references) from an object. - ### Arguments - `arg` [string]: Path to the object(s) to list refs from. Required: **yes**. @@ -3920,11 +3924,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/refs/local List all local references. - ### Arguments This endpoint takes no arguments. @@ -3948,11 +3952,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/repo/fsck Remove repo lockfiles. - ### Arguments This endpoint takes no arguments. @@ -3975,11 +3979,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/repo/gc Perform a garbage collection sweep on the repo. - ### Arguments - `stream-errors` [bool]: Stream errors. Required: no. @@ -4006,11 +4010,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/repo/stat Get stats for the currently used repo. - ### Arguments - `size-only` [bool]: Only report RepoSize and StorageMax. Required: no. @@ -4040,11 +4044,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/repo/verify Verify all blocks in repo are not corrupted. - ### Arguments This endpoint takes no arguments. @@ -4068,11 +4072,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/repo/version Show the repo version. - ### Arguments - `quiet` [bool]: Write minimal output. Required: no. @@ -4095,11 +4099,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/resolve Resolve the value of names to IPFS. - ### Arguments - `arg` [string]: The name to resolve. Required: **yes**. @@ -4125,11 +4129,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/shutdown Shut down the IPFS daemon. - ### Arguments This endpoint takes no arguments. @@ -4149,11 +4153,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/stats/bitswap Show some diagnostic information on the bitswap agent. - ### Arguments - `verbose` [bool]: Print extra information. Required: no. @@ -4192,11 +4196,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/stats/bw Print IPFS bandwidth information. - ### Arguments - `peer` [string]: Specify a peer to print bandwidth for. Required: no. @@ -4228,11 +4232,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/stats/dht Returns statistics about the node's DHT(s). - ### Arguments - `arg` [string]: The DHT whose table should be listed (wanserver, lanserver, wan, lan). wan and lan refer to client routing tables. When using the experimental DHT client only WAN is supported. Defaults to wan and lan. Required: no. @@ -4269,11 +4273,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/stats/provide Returns statistics about the node's (re)provider system. - ### Arguments This endpoint takes no arguments. @@ -4299,11 +4303,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/stats/repo Get stats for the currently used repo. - ### Arguments - `size-only` [bool]: Only report RepoSize and StorageMax. Required: no. @@ -4333,11 +4337,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/addrs List known addresses. Useful for debugging. - ### Arguments This endpoint takes no arguments. @@ -4364,11 +4368,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/addrs/listen List interface listening addresses. - ### Arguments This endpoint takes no arguments. @@ -4393,11 +4397,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/addrs/local List local addresses. - ### Arguments - `id` [bool]: Show peer ID in addresses. Required: no. @@ -4422,11 +4426,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/connect Open connection to a given address. - ### Arguments - `arg` [string]: Address of peer to connect to. Required: **yes**. @@ -4451,11 +4455,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/disconnect Close connection to a given address. - ### Arguments - `arg` [string]: Address of peer to disconnect from. Required: **yes**. @@ -4480,11 +4484,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/filters Manipulate address filters. - ### Arguments This endpoint takes no arguments. @@ -4509,11 +4513,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/filters/add Add an address filter. - ### Arguments - `arg` [string]: Multiaddr to filter. Required: **yes**. @@ -4538,11 +4542,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/filters/rm Remove an address filter. - ### Arguments - `arg` [string]: Multiaddr filter to remove. Required: **yes**. @@ -4567,11 +4571,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/peering/add Add peers into the peering subsystem. - ### Arguments - `arg` [string]: address of peer to add into the peering subsystem Required: **yes**. @@ -4595,11 +4599,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/peering/ls List peers registered in the peering subsystem. - ### Arguments This endpoint takes no arguments. @@ -4629,11 +4633,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/peering/rm Remove a peer from the peering subsystem. - ### Arguments - `arg` [string]: ID of peer to remove from the peering subsystem Required: **yes**. @@ -4657,11 +4661,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/swarm/peers List peers with open connections. - ### Arguments - `verbose` [bool]: display all extra information. Required: no. @@ -4700,11 +4704,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/tar/add Import a tar file into IPFS. - ### Arguments @@ -4735,11 +4739,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/tar/cat Export a tar file from IPFS. - ### Arguments - `arg` [string]: ipfs path of archive to export. Required: **yes**. @@ -4759,8 +4763,8 @@ This endpoint returns a `text/plain` response body. --- -## /api/v0/update +## /api/v0/update @@ -4783,11 +4787,11 @@ This endpoint returns a `text/plain` response body. --- + ## /api/v0/urlstore/add Add URL via urlstore. - ### Arguments - `arg` [string]: URL to add to IPFS Required: **yes**. @@ -4813,11 +4817,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/version Show IPFS version information. - ### Arguments - `number` [bool]: Only show the version number. Required: no. @@ -4847,11 +4851,11 @@ On success, the call to this endpoint will return with 200 and the following bod --- + ## /api/v0/version/deps Shows information about dependencies used for build. - ### Arguments This endpoint takes no arguments. diff --git a/tools/http-api-docs/endpoints.go b/tools/http-api-docs/endpoints.go index e89ce3bb2..4736fbf6b 100644 --- a/tools/http-api-docs/endpoints.go +++ b/tools/http-api-docs/endpoints.go @@ -45,6 +45,7 @@ const MaxIndent = 20 // Endpoint defines an IPFS RPC API endpoint. type Endpoint struct { Name string + Status cmds.Status Arguments []*Argument Options []*Argument Description string @@ -75,6 +76,16 @@ func AllEndpoints() []*Endpoint { return Endpoints(APIPrefix, corecmds.Root) } +func InStatus(endpoints []*Endpoint, status cmds.Status) []*Endpoint { + var results []*Endpoint + for _, endpoint := range endpoints { + if endpoint.Status == status { + results = append(results, endpoint) + } + } + return results +} + func IPFSVersion() string { return config.CurrentVersionNumber } @@ -128,6 +139,7 @@ func Endpoints(name string, cmd *cmds.Command) (endpoints []*Endpoint) { endpoints = []*Endpoint{ { Name: name, + Status: cmd.Status, Description: cmd.Helptext.Tagline, Arguments: arguments, Options: options, diff --git a/tools/http-api-docs/formatter.go b/tools/http-api-docs/formatter.go index ec32ff2fa..07cc3f415 100644 --- a/tools/http-api-docs/formatter.go +++ b/tools/http-api-docs/formatter.go @@ -1,10 +1,15 @@ package docs -import "bytes" +import ( + "bytes" + + cmds "github.com/ipfs/go-ipfs-cmds" +) // Formatter allows to implement generation of docs in different formats. type Formatter interface { GenerateIntro() string + GenerateStatusIntro(status cmds.Status) string GenerateIndex(endp []*Endpoint) string GenerateEndpointBlock(endp *Endpoint) string GenerateArgumentsBlock(args []*Argument, opts []*Argument) string @@ -17,14 +22,20 @@ type Formatter interface { func GenerateDocs(api []*Endpoint, formatter Formatter) string { buf := new(bytes.Buffer) buf.WriteString(formatter.GenerateIntro()) - // In docs.ipfs.io this is handled by the TOC. - // buf.WriteString(formatter.GenerateIndex(api)) - for _, endp := range api { - buf.WriteString(formatter.GenerateEndpointBlock(endp)) - buf.WriteString(formatter.GenerateArgumentsBlock(endp.Arguments, endp.Options)) - buf.WriteString(formatter.GenerateBodyBlock(endp.Arguments)) - buf.WriteString(formatter.GenerateResponseBlock(endp.Response)) - buf.WriteString(formatter.GenerateExampleBlock(endp)) + + for _, status := range []cmds.Status{cmds.Active, cmds.Experimental, cmds.Deprecated, cmds.Removed} { + endpoints := InStatus(api, status) + if len(endpoints) == 0 { + continue + } + buf.WriteString(formatter.GenerateStatusIntro(status)) + for _, endp := range endpoints { + buf.WriteString(formatter.GenerateEndpointBlock(endp)) + buf.WriteString(formatter.GenerateArgumentsBlock(endp.Arguments, endp.Options)) + buf.WriteString(formatter.GenerateBodyBlock(endp.Arguments)) + buf.WriteString(formatter.GenerateResponseBlock(endp.Response)) + buf.WriteString(formatter.GenerateExampleBlock(endp)) + } } return buf.String() } diff --git a/tools/http-api-docs/go.mod b/tools/http-api-docs/go.mod index eaa869c8a..2d28ebc48 100644 --- a/tools/http-api-docs/go.mod +++ b/tools/http-api-docs/go.mod @@ -1,12 +1,12 @@ -module github.com/ipfs/http-api-docs +module http-api-docs go 1.16 require ( github.com/Stebalien/go-json-doc v0.0.2 github.com/ipfs/go-cid v0.1.0 - github.com/ipfs/go-ipfs v0.12.1 - github.com/ipfs/go-ipfs-cmds v0.6.0 + github.com/ipfs/go-ipfs v0.12.2 + github.com/ipfs/go-ipfs-cmds v0.7.0 github.com/libp2p/go-libp2p-core v0.11.0 github.com/multiformats/go-multiaddr v0.4.1 ) diff --git a/tools/http-api-docs/go.sum b/tools/http-api-docs/go.sum index abee3d03e..02eb4cb3b 100644 --- a/tools/http-api-docs/go.sum +++ b/tools/http-api-docs/go.sum @@ -453,8 +453,8 @@ github.com/ipfs/go-fs-lock v0.0.7 h1:6BR3dajORFrFTkb5EpCUFIAypsoxpGpDSVUdFwzgL9U github.com/ipfs/go-fs-lock v0.0.7/go.mod h1:Js8ka+FNYmgQRLrRXzU3CB/+Csr1BwrRilEcvYrHhhc= github.com/ipfs/go-graphsync v0.11.0 h1:PiiD5CnoC3xEHMW8d6uBGqGcoTwiMB5d9CORIEyF6iA= github.com/ipfs/go-graphsync v0.11.0/go.mod h1:wC+c8vGVjAHthsVIl8LKr37cUra2GOaMYcQNNmMxDqE= -github.com/ipfs/go-ipfs v0.12.1 h1:stT4AJCiaTS2a+yL382g1IB8Gm+jJFqe7Ssvf+L9KNw= -github.com/ipfs/go-ipfs v0.12.1/go.mod h1:Sbei4ScHevs2v47nUgONQMtHlUfaJjjTNDbhUU1OzOM= +github.com/ipfs/go-ipfs v0.12.2 h1:tXE5L4Y67nvftc2+tOgUuO1DG+IPze6s9MKxp75D3yo= +github.com/ipfs/go-ipfs v0.12.2/go.mod h1:Li5Vnr499spscpLQQ88HXxQW4MtJBBdYKjYcJEHb8jU= github.com/ipfs/go-ipfs-blockstore v0.0.1/go.mod h1:d3WClOmRQKFnJ0Jz/jj/zmksX0ma1gROTlovZKBmN08= github.com/ipfs/go-ipfs-blockstore v0.1.0/go.mod h1:5aD0AvHPi7mZc6Ci1WCAhiBQu2IsfTduLl+422H6Rqw= github.com/ipfs/go-ipfs-blockstore v0.1.4/go.mod h1:Jxm3XMVjh6R17WvxFEiyKBLUGr86HgIYJW/D/MwqeYQ= @@ -468,8 +468,9 @@ github.com/ipfs/go-ipfs-blocksutil v0.0.1/go.mod h1:Yq4M86uIOmxmGPUHv/uI7uKqZNtL github.com/ipfs/go-ipfs-chunker v0.0.1/go.mod h1:tWewYK0we3+rMbOh7pPFGDyypCtvGcBFymgY4rSDLAw= github.com/ipfs/go-ipfs-chunker v0.0.5 h1:ojCf7HV/m+uS2vhUGWcogIIxiO5ubl5O57Q7NapWLY8= github.com/ipfs/go-ipfs-chunker v0.0.5/go.mod h1:jhgdF8vxRHycr00k13FM8Y0E+6BoalYeobXmUyTreP8= -github.com/ipfs/go-ipfs-cmds v0.6.0 h1:yAxdowQZzoFKjcLI08sXVNnqVj3jnABbf9smrPQmBsw= github.com/ipfs/go-ipfs-cmds v0.6.0/go.mod h1:ZgYiWVnCk43ChwoH8hAmI1IRbuVtq3GSTHwtRB/Kqhk= +github.com/ipfs/go-ipfs-cmds v0.7.0 h1:0lEldmB7C83RxIOer38Sv1ob6wIoCAIEOaxiYgcv7wA= +github.com/ipfs/go-ipfs-cmds v0.7.0/go.mod h1:y0bflH6m4g6ary4HniYt98UqbrVnRxmRarzeMdLIUn0= github.com/ipfs/go-ipfs-config v0.18.0 h1:Ta1aNGNEq6RIvzbw7dqzCVZJKb7j+Dd35JFnAOCpT8g= github.com/ipfs/go-ipfs-config v0.18.0/go.mod h1:wz2lKzOjgJeYJa6zx8W9VT7mz+iSd0laBMqS/9wmX6A= github.com/ipfs/go-ipfs-delay v0.0.0-20181109222059-70721b86a9a8/go.mod h1:8SP1YXK1M1kXuc4KJZINY3TQQ03J2rwBG9QfXmbRPrw= @@ -577,8 +578,9 @@ github.com/ipfs/tar-utils v0.0.2/go.mod h1:4qlnRWgTVljIMhSG2SqRYn66NT+3wrv/kZt9V github.com/ipld/go-car v0.3.2 h1:V9wt/80FNfbMRWSD98W5br6fyjUAyVgI2lDOTZX16Lg= github.com/ipld/go-car v0.3.2/go.mod h1:WEjynkVt04dr0GwJhry0KlaTeSDEiEYyMPOxDBQ17KE= github.com/ipld/go-codec-dagpb v1.2.0/go.mod h1:6nBN7X7h8EOsEejZGqC7tej5drsdBAXbMHyBT+Fne5s= -github.com/ipld/go-codec-dagpb v1.3.0 h1:czTcaoAuNNyIYWs6Qe01DJ+sEX7B+1Z0LcXjSatMGe8= github.com/ipld/go-codec-dagpb v1.3.0/go.mod h1:ga4JTU3abYApDC3pZ00BC2RSvC3qfBb9MSJkMLSwnhA= +github.com/ipld/go-codec-dagpb v1.3.2 h1:MZQUIjanHXXfDuYmtWYT8nFbqfFsZuyHClj6VDmSXr4= +github.com/ipld/go-codec-dagpb v1.3.2/go.mod h1:ga4JTU3abYApDC3pZ00BC2RSvC3qfBb9MSJkMLSwnhA= github.com/ipld/go-ipld-prime v0.9.0/go.mod h1:KvBLMr4PX1gWptgkzRjVZCrLmSGcZCb/jioOQwCqZN8= github.com/ipld/go-ipld-prime v0.9.1-0.20210324083106-dc342a9917db/go.mod h1:KvBLMr4PX1gWptgkzRjVZCrLmSGcZCb/jioOQwCqZN8= github.com/ipld/go-ipld-prime v0.11.0/go.mod h1:+WIAkokurHmZ/KwzDOMUuoeJgaRQktHtEaLglS3ZeV8= diff --git a/tools/http-api-docs/http-api-docs/main.go b/tools/http-api-docs/http-api-docs/main.go index 4bdabd1df..dbc17b53b 100644 --- a/tools/http-api-docs/http-api-docs/main.go +++ b/tools/http-api-docs/http-api-docs/main.go @@ -3,7 +3,8 @@ package main import ( "fmt" - "github.com/ipfs/http-api-docs" + + docs "http-api-docs" ) func main() { diff --git a/tools/http-api-docs/markdown.go b/tools/http-api-docs/markdown.go index f3e0dc402..fcf432f33 100644 --- a/tools/http-api-docs/markdown.go +++ b/tools/http-api-docs/markdown.go @@ -7,6 +7,8 @@ import ( "regexp" "strings" "time" + + cmds "github.com/ipfs/go-ipfs-cmds" ) // MarkdownFormatter implements a markdown doc generator. It is @@ -181,7 +183,6 @@ A `+"`405`"+` error may mean that you are using the wrong HTTP method (i.e. GET When a request is sent from a browser, HTTP RPC API follows the [Origin-based security model](https://en.wikipedia.org/wiki/Same-origin_policy), and expects the `+"`Origin`"+` HTTP header to be present. The API will return HTTP Error 403 when Origin is missing, does not match the API port, or is not safelisted via `+"`API.HTTPHeaders.Access-Control-Allow-Origin`"+` in the config. -## HTTP RPC commands `, time.Now().Format("2006-01-02"), IPFSVersion(), @@ -191,6 +192,63 @@ The API will return HTTP Error 403 when Origin is missing, does not match the AP return buf.String() } +func (md *MarkdownFormatter) GenerateStatusIntro(status cmds.Status) string { + return fmt.Sprintf(` +## %s RPC commands + +%s + +`, statusLabel(status), statusDescription(status)) +} + +func statusLabel(status cmds.Status) string { + switch status { + case cmds.Active: + return "" + case cmds.Deprecated: + return "Deprecated" + case cmds.Experimental: + return "Experimental" + case cmds.Removed: + return "Removed" + default: + panic("unknown command status") + } +} + +func statusDescription(status cmds.Status) string { + switch status { + case cmds.Active: + return "" + case cmds.Deprecated: + return "Below commands are deprecated and will be removed in the future." + case cmds.Experimental: + return "Below commands are experimental and should be used with care. The API may change in future releases." + case cmds.Removed: + return "Below commands were removed, listing them here only for documentation purposes." + default: + panic("unknown command status") + } +} + +func statusInfobox(status cmds.Status) string { + switch status { + case cmds.Active: + return "" // noop + case cmds.Deprecated, cmds.Experimental, cmds.Removed: + st := statusLabel(status) + return fmt.Sprintf(` +::: warning %s + +This command is %s. + +::: +`, strings.ToUpper(st), strings.ToLower(st)) + default: + panic("unknown command status") + } +} + func (md *MarkdownFormatter) GenerateIndex(endps []*Endpoint) string { buf := new(bytes.Buffer) fmt.Fprintf(buf, "## Index\n\n") @@ -208,12 +266,12 @@ func (md *MarkdownFormatter) GenerateIndex(endps []*Endpoint) string { func (md *MarkdownFormatter) GenerateEndpointBlock(endp *Endpoint) string { buf := new(bytes.Buffer) fmt.Fprintf(buf, ` -## %s +## %s +%s %s - -`, endp.Name, html.EscapeString(endp.Description)) +`, endp.Name, statusInfobox(endp.Status), html.EscapeString(endp.Description)) return buf.String() }