Skip to content

Commit

Permalink
Merge pull request dragonflyoss#275 from pouchrobot/auto-doc-2018-12-21
Browse files Browse the repository at this point in the history 
docs: auto generate Dragonfly cli/api docs via code
  • Loading branch information
@lowzj
lowzj authored Dec 21, 2018
2 parents 24d6eec + e2e760f commit 01993c9
Showing 1 changed file with 36 additions and 43 deletions.
79 changes: 36 additions & 43 deletions docs/apis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```
Expand All @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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|


Expand All @@ -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>
Expand Down Expand Up @@ -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|

Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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|



Expand Down

0 comments on commit 01993c9

Please sign in to comment.