Merge pull request dragonflyoss#275 from pouchrobot/auto-doc-2018-12-21

docs: auto generate Dragonfly cli/api docs via code

Author: lowzj

docs/apis.md

@@ -197,7 +197,11 @@ PUT /pieces/{id}
 
 
 #### Description
-Update some information of piece, like status of piece.
+Update some information of piece. When peer A finishes to download
+piece B, A must send request to supernode to update piece B's info
+to mark that peer A has the complete piece B. Then when other peers 
+request to download this piece B, supernode could schedule peer A
+to those peers.
 
 
 #### Parameters
@@ -378,7 +382,8 @@ PUT /tasks/{id}
 
 
 #### Description
-update information of a task.
+update information of a task. When a peer finishes to download all pieces of a task,
+it must update peer downloading status of this task in supernode.
 
 
 #### Parameters
@@ -408,33 +413,6 @@ update information of a task.
 * `application/json`
 
 
-<a name="tasks-id-delete"></a>
-### delete a task
-```
-DELETE /tasks/{id}
-```
-
-
-#### Description
-delete a peer-to-peer task in supernode.
-
-
-#### Parameters
-
-|Type|Name|Description|Schema|
-|---|---|---|---|
-|**Path**|**id**  <br>*required*|ID of task|string|
-
-
-#### Responses
-
-|HTTP Code|Description|Schema|
-|---|---|---|
-|**204**|no error|No Content|
-|**404**|no such peer|[4ErrorResponse](#4errorresponse)|
-|**500**|An unexpected server error occurred.|[Error](#error)|
-
-
 <a name="tasks-id-pieces-get"></a>
 ### Get pieces in task
 ```
@@ -443,7 +421,9 @@ GET /tasks/{id}/pieces
 
 
 #### Description
-Get fixed number of pieces in a task. The number is set in query.
+When dfget starts to download pieces of a task, it should get fixed
+number of pieces in a task and the use pieces information to download
+the pirces. The request piece number is set in query.
 
 
 #### Parameters
@@ -503,12 +483,9 @@ it will send PeerCreateRequest to supernode.
 |---|---|---|
 |**ID**  <br>*optional*|Peer ID of dfget client. Every peer has a unique ID among peer network.|string|
 |**IP**  <br>*optional*|IP address which peer client carries|string (ipv4)|
-|**callSystem**  <br>*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem<br>name to dfget. When this field is passing to supernode, supernode has ability to filter them via <br>some black/white list to guarantee security, or some other purposes.  <br>**Minimum length** : `1`|string|
-|**dfdaemon**  <br>*optional*|tells whether it is a call from dfdaemon.|boolean|
 |**hostName**  <br>*optional*|host name of peer client node, as a valid RFC 1123 hostname.  <br>**Minimum length** : `1`|string (hostname)|
-|**path**  <br>*optional*|This is actually an HTTP URLPATH of dfget. <br>Other peers can access the source file via this PATH.|string|
-|**port**  <br>*optional*|when registering, dfget will setup one uploader process. <br>This one acts as a server for peer pulling tasks.<br>This port is which this server listens on.  <br>**Minimum value** : `30000`  <br>**Maximum value** : `65535`|integer (int64)|
-|**version**  <br>*optional*|version number of dfget binary|string|
+|**port**  <br>*optional*|when registering, dfget will setup one uploader process. <br>This one acts as a server for peer pulling tasks.<br>This port is which this server listens on.  <br>**Minimum value** : `15000`  <br>**Maximum value** : `65000`|integer (int32)|
+|**version**  <br>*optional*|version number of dfget binary.|string|
 
 
 <a name="peercreateresponse"></a>
@@ -530,11 +507,8 @@ The detailed information of a peer in supernode.
 |---|---|---|
 |**ID**  <br>*optional*|ID of peer|string|
 |**IP**  <br>*optional*|IP address which peer client carries|string (ipv4)|
-|**callSystem**  <br>*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem<br>name to dfget. When this field is passing to supernode, supernode has ability to filter them via <br>some black/white list to guarantee security, or some other purposes.  <br>**Minimum length** : `1`|string|
-|**dfdaemon**  <br>*optional*|tells whether it is a call from dfdaemon.|boolean|
 |**hostName**  <br>*optional*|host name of peer client node, as a valid RFC 1123 hostname.  <br>**Minimum length** : `1`|string (hostname)|
-|**path**  <br>*optional*|This is actually an HTTP URLPATH of dfget. <br>Other peers can access the source file via this PATH.|string|
-|**port**  <br>*optional*|when registering, dfget will setup one uploader process. <br>This one acts as a server for peer pulling tasks.<br>This port is which this server listens on.  <br>**Minimum value** : `30000`  <br>**Maximum value** : `65535`|integer (int64)|
+|**port**  <br>*optional*|when registering, dfget will setup one uploader process. <br>This one acts as a server for peer pulling tasks.<br>This port is which this server listens on.  <br>**Minimum value** : `15000`  <br>**Maximum value** : `65000`|integer (int32)|
 |**version**  <br>*optional*|version number of dfget binary|string|
 
 
@@ -550,10 +524,12 @@ Peer's detailed information in supernode.
 
 <a name="pieceupdaterequest"></a>
 ### PieceUpdateRequest
+request peer uses to update its status of downloading piece in supernode.
 
-|Name|Schema|
-|---|---|
-|**ID**  <br>*optional*|string|
+
+|Name|Description|Schema|
+|---|---|---|
+|**PeerID**  <br>*optional*|contains the peer ID.|string|
 
 
 <a name="preheatcreaterequest"></a>
@@ -599,9 +575,12 @@ task because that an image may have more than one layer.
 
 |Name|Description|Schema|
 |---|---|---|
+|**callSystem**  <br>*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem<br>name to dfget. When this field is passing to supernode, supernode has ability to filter them via <br>some black/white list to guarantee security, or some other purposes.  <br>**Minimum length** : `1`|string|
+|**dfdaemon**  <br>*optional*|tells whether it is a call from dfdaemon. dfdaemon is a long running<br>process which works for container engines. It translates the image<br>pulling request into raw requests into those dfget recganises.|boolean|
 |**headers**  <br>*optional*|extra HTTP headers sent to the rawURL.<br>This field is carried with the request to supernode. <br>Supernode will extract these HTTP headers, and set them in HTTP downloading requests<br>from source server as user's wish.|< string, string > map|
 |**identifier**  <br>*optional*|special attribute of remote source file. This field is used with taskURL to generate new taskID to<br>indetify different downloading task of remote source file. For example, if user A and user B uses<br>the same taskURL and taskID to download file, A and B will share the same peer network to distribute files.<br>If user A additionally adds an indentifier with taskURL, while user B still carries only taskURL, then A's<br>generated taskID is different from B, and the result is that two users use different peer networks.|string|
 |**md5**  <br>*optional*|md5 checksum for the resource to distribute. dfget catches this parameter from dfget's CLI<br>and passes it to supernode. When supernode finishes downloading file/image from the source location,<br>it will validate the source file with this md5 value to check whether this is a valid file.|string|
+|**path**  <br>*optional*|path is used in one peer A for uploading functionality. When peer B hopes<br>to get piece C from peer A, B must provide a URL for piece C.<br>Then when creating a task in supernode, peer A must provide this URL in request.|string|
 |**rawURL**  <br>*optional*|The is the resource's URL which user uses dfget to download. The location of URL can be anywhere, LAN or WAN.<br>For image distribution, this is image layer's URL in image registry.<br>The resource url is provided by command line parameter.|string|
 |**taskURL**  <br>*optional*|taskURL is generated from rawURL. rawURL may contains some queries or parameter, dfget will filter some queries via<br>--filter parameter of dfget. The usage of it is that different rawURL may generate the same taskID.|string|
 
@@ -613,7 +592,9 @@ response get from task creation request.
 
 |Name|Description|Schema|
 |---|---|---|
+|**FileLength**  <br>*optional*|The length of the file dfget requests to download in bytes.|integer (int64)|
 |**ID**  <br>*optional*|ID of the created task.|string|
+|**PieceSize**  <br>*optional*|The size of pieces which is calculated as per the following strategy<br>1. If file's total size is less than 200MB, then the piece size is 4MB by default.<br>2. Otherwise, it equals to the smaller value between totalSize/100MB + 2 MB and 15MB.|integer (int32)|
 
 
 <a name="taskinfo"></a>
@@ -623,7 +604,19 @@ detailed information about task in supernode.
 
 |Name|Description|Schema|
 |---|---|---|
+|**CdnStatus**  <br>*optional*|The status of the created task related to CDN functionality.|enum (WAITING, RUNNING, FAILED, SUCCESS, SOURCE_ERROR)|
+|**FileLength**  <br>*optional*|The length of the file dfget requests to download in bytes.|integer (int64)|
 |**ID**  <br>*optional*|ID of the task.|string|
+|**PieceSize**  <br>*optional*|The size of pieces which is calculated as per the following strategy<br>1. If file's total size is less than 200MB, then the piece size is 4MB by default.<br>2. Otherwise, it equals to the smaller value between totalSize/100MB + 2 MB and 15MB.|integer (int32)|
+|**PieceTotal**  <br>*optional*||integer (int32)|
+|**callSystem**  <br>*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem<br>name to dfget. When this field is passing to supernode, supernode has ability to filter them via <br>some black/white list to guarantee security, or some other purposes.  <br>**Minimum length** : `1`|string|
+|**dfdaemon**  <br>*optional*|tells whether it is a call from dfdaemon. dfdaemon is a long running<br>process which works for container engines. It translates the image<br>pulling request into raw requests into those dfget recganises.|boolean|
+|**headers**  <br>*optional*|extra HTTP headers sent to the rawURL.<br>This field is carried with the request to supernode. <br>Supernode will extract these HTTP headers, and set them in HTTP downloading requests<br>from source server as user's wish.|< string, string > map|
+|**identifier**  <br>*optional*|special attribute of remote source file. This field is used with taskURL to generate new taskID to<br>indetify different downloading task of remote source file. For example, if user A and user B uses<br>the same taskURL and taskID to download file, A and B will share the same peer network to distribute files.<br>If user A additionally adds an indentifier with taskURL, while user B still carries only taskURL, then A's<br>generated taskID is different from B, and the result is that two users use different peer networks.|string|
+|**md5**  <br>*optional*|md5 checksum for the resource to distribute. dfget catches this parameter from dfget's CLI<br>and passes it to supernode. When supernode finishes downloading file/image from the source location,<br>it will validate the source file with this md5 value to check whether this is a valid file.|string|
+|**path**  <br>*optional*|path is used in one peer A for uploading functionality. When peer B hopes<br>to get piece C from peer A, B must provide a URL for piece C.<br>Then when creating a task in supernode, peer A must provide this URL in request.|string|
+|**rawURL**  <br>*optional*|The is the resource's URL which user uses dfget to download. The location of URL can be anywhere, LAN or WAN.<br>For image distribution, this is image layer's URL in image registry.<br>The resource url is provided by command line parameter.|string|
+|**taskURL**  <br>*optional*|taskURL is generated from rawURL. rawURL may contains some queries or parameter, dfget will filter some queries via<br>--filter parameter of dfget. The usage of it is that different rawURL may generate the same taskID.|string|
 
 
 <a name="taskupdaterequest"></a>
@@ -633,7 +626,7 @@ request used to update task attributes.
 
 |Name|Description|Schema|
 |---|---|---|
-|**ID**  <br>*optional*|ID of the created task.|string|
+|**PeerID**  <br>*optional*|ID of the peer which has finished to download the whole task.|string|