From c69bc354d8c7c72f26b30b8aea35f4898e1e7f80 Mon Sep 17 00:00:00 2001 From: pouchrobot Date: Tue, 12 May 2020 01:24:42 +0000 Subject: [PATCH] docs: auto generate Dragonfly cli/api docs via code Signed-off-by: pouchrobot --- CONTRIBUTORS | 1 + docs/api_reference/apis.md | 63 +++++++++++++++++++++++++++++++++++--- 2 files changed, 60 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 48624b5a7..1ff7d0446 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -31,6 +31,7 @@ Guangming Wang Guangwen Feng Haines Chan Haosdent Huang +henry.hj Hu Shuai huaxiao Hui Zhao <176425810@qq.com> diff --git a/docs/api_reference/apis.md b/docs/api_reference/apis.md index af860a778..c8b44181d 100644 --- a/docs/api_reference/apis.md +++ b/docs/api_reference/apis.md @@ -213,6 +213,7 @@ request to setup a peer-to-peer network immediately. |---|---|---| |**200**|no error|[PreheatCreateResponse](#preheatcreateresponse)| |**400**|bad parameter|[Error](#error)| +|**409**|preheat task already exists|[Error](#error)| |**500**|An unexpected server error occurred.|[Error](#error)| @@ -270,6 +271,38 @@ get detailed information of a preheat task in supernode. * `application/json` + +### Delete a preheat task +``` +DELETE /api/v1/preheats/{id} +``` + + +#### Description +delete a preheat task + + +#### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Path**|**id**
*required*|ID of preheat task|string| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|no error|No Content| +|**404**|no such preheat task|[4ErrorResponse](#4errorresponse)| +|**500**|An unexpected server error occurred.|[Error](#error)| + + +#### Produces + +* `application/json` + + ### create a task ``` @@ -572,7 +605,7 @@ And supernode could know if peer is alive in strem mode. |HTTP Code|Description|Schema| |---|---|---| -|**200**|no error|[ResultInfo](#resultinfo)| +|**200**|no error|[HeartBeatResponse](#heartbeatresponse)| |**500**|An unexpected server error occurred.|[Error](#error)| @@ -858,6 +891,16 @@ The request is to report peer to supernode to keep alive. |**port**
*optional*|when registering, dfget will setup one uploader process.
This one acts as a server for peer pulling tasks.
This port is which this server listens on.
**Minimum value** : `15000`
**Maximum value** : `65000`|integer (int32)| + +### HeartBeatResponse + +|Name|Description|Schema| +|---|---|---| +|**needRegister**
*optional*|If peer do not register in supernode, set needRegister to be true, else set to be false.|boolean| +|**seedTaskIDs**
*optional*|The array of seed taskID which now are selected as seed for the peer. If peer have other seed file which
is not included in the array, these seed file should be weed out.|< string > array| +|**version**
*optional*|The version of supernode. If supernode restarts, version should be different, so dfdaemon could know
the restart of supernode.|string| + + ### NetworkInfoFetchRequest The request is to fetch p2p network info from supernode. @@ -999,8 +1042,8 @@ Request option of creating a preheat task in supernode. |**filter**
*optional*|URL may contains some changeful query parameters such as authentication parameters. Dragonfly will
filter these parameter via 'filter'. The usage of it is that different URL may generate the same
download taskID.|string| |**headers**
*optional*|If there is any authentication step of the remote server, the headers should contains authenticated information.
Dragonfly will sent request taking the headers to remote server.|< string, string > map| |**identifier**
*optional*|This field is used for generating new downloading taskID to identify different downloading task of remote URL.|string| -|**type**
*optional*|this must be image or file|string| -|**url**
*optional*|the image or file location|string| +|**type**
*required*|this must be image or file|enum (image, file)| +|**url**
*required*|the image or file location
**Minimum length** : `3`|string| @@ -1024,7 +1067,19 @@ task because that an image may have more than one layer. |**ID**
*optional*|ID of preheat task.|string| |**finishTime**
*optional*|the preheat task finish time|string (date-time)| |**startTime**
*optional*|the preheat task start time|string (date-time)| -|**status**
*optional*|The status of preheat task.
WAITING -----> RUNNING -----> SUCCESS
\|--> FAILED
The initial status of a created preheat task is WAITING.
It's finished when a preheat task's status is FAILED or SUCCESS.
A finished preheat task's information can be queried within 24 hours.|enum (WAITING, RUNNING, FAILED, SUCCESS)| +|**status**
*optional*|The status of preheat task.
WAITING -----> RUNNING -----> SUCCESS
\|--> FAILED
The initial status of a created preheat task is WAITING.
It's finished when a preheat task's status is FAILED or SUCCESS.
A finished preheat task's information can be queried within 24 hours.|[PreheatStatus](#preheatstatus)| + + + +### PreheatStatus +The status of preheat task. + WAITING -----> RUNNING -----> SUCCESS + |--> FAILED +The initial status of a created preheat task is WAITING. +It's finished when a preheat task's status is FAILED or SUCCESS. +A finished preheat task's information can be queried within 24 hours. + +*Type* : enum (WAITING, RUNNING, FAILED, SUCCESS)