Refactor deploy_keys API documentation [ci skip]doc_refactor_deploy_keys_api

1 files changed, 62 insertions, 12 deletions

diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index e4492fc609c..9da1fe22e61 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -8,9 +8,15 @@ Get a list of a project's deploy keys.
 GET /projects/:id/keys
 ```
 
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys"
+```
 
-- `id` (required) - The ID of the project
+Example response:
 
 ```json
 [
@@ -39,8 +45,16 @@ GET /projects/:id/keys/:key_id
 
 Parameters:
 
-- `id` (required) - The ID of the project
-- `key_id` (required) - The ID of the deploy key
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+| `key_id`  | integer | yes | The ID of the deploy key |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/11"
+```
+
+Example response:
 
 ```json
 {
@@ -54,17 +68,34 @@ Parameters:
 ## Add deploy key
 
 Creates a new deploy key for a project.
-If deploy key already exists in another project - it will be joined to project but only if original one was is accessible by same user
+
+If the deploy key already exists in another project, it will be joined to current
+project only if original one was is accessible by the same user.
 
 ```
 POST /projects/:id/keys
 ```
 
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`    | integer | yes | The ID of the project |
+| `title` | string  | yes | New deploy key's title |
+| `key`   | string  | yes | New deploy key |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA..."}' "https://gitlab.example.com/api/v3/projects/5/keys/"
+```
 
-- `id` (required) - The ID of the project
-- `title` (required) - New deploy key's title
-- `key` (required) - New deploy key
+Example response:
+
+```json
+{
+   "key" : "ssh-rsa AAAA...",
+   "id" : 12,
+   "title" : "My deploy key",
+   "created_at" : "2015-08-29T12:44:31.550Z"
+}
+```
 
 ## Delete deploy key
 
@@ -74,7 +105,26 @@ Delete a deploy key from a project
 DELETE /projects/:id/keys/:key_id
 ```
 
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+| `key_id`  | integer | yes | The ID of the deploy key |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/13"
+```
 
-- `id` (required) - The ID of the project
-- `key_id` (required) - The ID of the deploy key
+Example response:
+
+```json
+{
+   "updated_at" : "2015-08-29T12:50:57.259Z",
+   "key" : "ssh-rsa AAAA...",
+   "public" : false,
+   "title" : "My deploy key",
+   "user_id" : null,
+   "created_at" : "2015-08-29T12:50:57.259Z",
+   "fingerprint" : "6a:33:1f:74:51:c0:39:81:79:ec:7a:31:f8:40:20:43",
+   "id" : 13
+}
+```