Download as
Browse Code »

Commit 68d146b4a692357354e25d0c0f93edf861b37e8c

Authored by Dmitriy Zaporozhets
1 parent b05600f2
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

Improve api docs

Showing 8 changed files with 233 additions and 345 deletions   Show diff stats
app/controllers/help_controller.rb
  Diff comments   View file @68d146b
1 class HelpController < ApplicationController 1 class HelpController < ApplicationController
2 def index 2 def index
3 end 3 end
  4 +
  5 + def api
  6 + @category = params[:category]
  7 + @category = "README" if @category.blank?
  8 +
  9 + if File.exists?(Rails.root.join('doc', 'api', @category + '.md'))
  10 + render 'api'
  11 + else
  12 + not_found!
  13 + end
  14 + end
4 end 15 end
app/views/help/_api_layout.html.haml 0 → 100644
  Diff comments   View file @68d146b
@@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
  1 +.row
  2 + .span3
  3 + = link_to help_path, class: 'btn append-bottom-20 btn-small' do
  4 + %i.icon-angle-left
  5 + Back to help
  6 + %br
  7 + %ul.nav.nav-pills.nav-stacked
  8 + - %w(README projects project_snippets repositories deploy_keys users session issues milestones notes system_hooks).each do |file|
  9 + %li{class: file == @category ? 'active' : nil}
  10 + = link_to file.titleize, help_api_file_path(file)
  11 +
  12 + .span9.pull-right
  13 + = yield
app/views/help/api.html.haml
  Diff comments   View file @68d146b
1 -= render layout: 'help/layout' do  
2 - %h3.page_title API 1 += render layout: 'help/api_layout' do
  2 + %h3.page_title
  3 + %span.light API
  4 + %span
  5 + \/
  6 + = @category.titleize
3 %br 7 %br
4 8
5 - %ul.nav.nav-tabs.log-tabs.nav-small-tabs  
6 - %li.active  
7 - = link_to "README", "#README", 'data-toggle' => 'tab'  
8 - %li  
9 - = link_to "Projects", "#projects", 'data-toggle' => 'tab'  
10 - %li  
11 - = link_to "Snippets", "#snippets", 'data-toggle' => 'tab'  
12 - %li  
13 - = link_to "Repositories", "#repositories", 'data-toggle' => 'tab'  
14 - %li  
15 - = link_to "Users", "#users", 'data-toggle' => 'tab'  
16 - %li  
17 - = link_to "Session", "#session", 'data-toggle' => 'tab'  
18 - %li  
19 - = link_to "Issues", "#issues", 'data-toggle' => 'tab'  
20 - %li  
21 - = link_to "Milestones", "#milestones", 'data-toggle' => 'tab'  
22 - %li  
23 - = link_to "Notes", "#notes", 'data-toggle' => 'tab'  
24 - %li  
25 - = link_to "System Hooks", "#system_hooks", 'data-toggle' => 'tab'  
26 -  
27 - .tab-content  
28 - .tab-pane.active#README  
29 - .file_holder  
30 - .file_title  
31 - %i.icon-file  
32 - README  
33 - .file_content.wiki  
34 - = preserve do  
35 - = markdown File.read(Rails.root.join("doc", "api", "README.md"))  
36 -  
37 - .tab-pane#projects  
38 - .file_holder  
39 - .file_title  
40 - %i.icon-file  
41 - Projects  
42 - .file_content.wiki  
43 - = preserve do  
44 - = markdown File.read(Rails.root.join("doc", "api", "projects.md"))  
45 -  
46 - .tab-pane#snippets  
47 - .file_holder  
48 - .file_title  
49 - %i.icon-file  
50 - Projects Snippets  
51 - .file_content.wiki  
52 - = preserve do  
53 - = markdown File.read(Rails.root.join("doc", "api", "snippets.md"))  
54 -  
55 - .tab-pane#repositories  
56 - .file_holder  
57 - .file_title  
58 - %i.icon-file  
59 - Projects  
60 - .file_content.wiki  
61 - = preserve do  
62 - = markdown File.read(Rails.root.join("doc", "api", "repositories.md"))  
63 -  
64 - .tab-pane#users  
65 - .file_holder  
66 - .file_title  
67 - %i.icon-file  
68 - Users  
69 - .file_content.wiki  
70 - = preserve do  
71 - = markdown File.read(Rails.root.join("doc", "api", "users.md"))  
72 -  
73 - .tab-pane#session  
74 - .file_holder  
75 - .file_title  
76 - %i.icon-file  
77 - Session  
78 - .file_content.wiki  
79 - = preserve do  
80 - = markdown File.read(Rails.root.join("doc", "api", "session.md"))  
81 -  
82 - .tab-pane#issues  
83 - .file_holder  
84 - .file_title  
85 - %i.icon-file  
86 - Issues  
87 - .file_content.wiki  
88 - = preserve do  
89 - = markdown File.read(Rails.root.join("doc", "api", "issues.md"))  
90 -  
91 - .tab-pane#milestones  
92 - .file_holder  
93 - .file_title  
94 - %i.icon-file  
95 - Milestones  
96 - .file_content.wiki  
97 - = preserve do  
98 - = markdown File.read(Rails.root.join("doc", "api", "milestones.md"))  
99 -  
100 - .tab-pane#notes  
101 - .file_holder  
102 - .file_title  
103 - %i.icon-file  
104 - Notes  
105 - .file_content.wiki  
106 - = preserve do  
107 - = markdown File.read(Rails.root.join("doc", "api", "notes.md"))  
108 -  
109 - .tab-pane#system_hooks  
110 - .file_holder  
111 - .file_title  
112 - %i.icon-file  
113 - System Hooks  
114 - .file_content.wiki  
115 - = preserve do  
116 - = markdown File.read(Rails.root.join("doc", "api", "system_hooks.md")) 9 + .file_holder
  10 + .file_title
  11 + %i.icon-file
  12 + = @category
  13 + .file_content.wiki
  14 + = preserve do
  15 + = markdown File.read(Rails.root.join("doc", "api", "#{@category}.md"))
config/routes.rb
  Diff comments   View file @68d146b
@@ -29,6 +29,7 @@ Gitlab::Application.routes.draw do @@ -29,6 +29,7 @@ Gitlab::Application.routes.draw do
29 # 29 #
30 get 'help' => 'help#index' 30 get 'help' => 'help#index'
31 get 'help/api' => 'help#api' 31 get 'help/api' => 'help#api'
  32 + get 'help/api/:category' => 'help#api', as: 'help_api_file'
32 get 'help/markdown' => 'help#markdown' 33 get 'help/markdown' => 'help#markdown'
33 get 'help/permissions' => 'help#permissions' 34 get 'help/permissions' => 'help#permissions'
34 get 'help/public_access' => 'help#public_access' 35 get 'help/public_access' => 'help#public_access'
doc/api/deploy_keys.md 0 → 100644
  Diff comments   View file @68d146b
@@ -0,0 +1,87 @@ @@ -0,0 +1,87 @@
  1 +## Deploy Keys
  2 +
  3 +### List deploy keys
  4 +
  5 +Get a list of a project's deploy keys.
  6 +
  7 +```
  8 +GET /projects/:id/keys
  9 +```
  10 +
  11 +Parameters:
  12 +
  13 ++ `id` (required) - The ID of the project
  14 +
  15 +```json
  16 +[
  17 + {
  18 + "id": 1,
  19 + "title" : "Public key"
  20 + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
  21 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
  22 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  23 + },
  24 + {
  25 + "id": 3,
  26 + "title" : "Another Public key"
  27 + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
  28 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
  29 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
  30 + }
  31 +]
  32 +```
  33 +
  34 +
  35 +### Single deploy key
  36 +
  37 +Get a single key.
  38 +
  39 +```
  40 +GET /projects/:id/keys/:key_id
  41 +```
  42 +
  43 +Parameters:
  44 +
  45 ++ `id` (required) - The ID of the project
  46 ++ `key_id` (required) - The ID of the deploy key
  47 +
  48 +```json
  49 +{
  50 + "id": 1,
  51 + "title" : "Public key"
  52 + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
  53 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
  54 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
  55 +}
  56 +```
  57 +
  58 +
  59 +### Add deploy key
  60 +
  61 +Creates a new deploy key for a project.
  62 +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
  63 +
  64 +```
  65 +POST /projects/:id/keys
  66 +```
  67 +
  68 +Parameters:
  69 +
  70 ++ `id` (required) - The ID of the project
  71 ++ `title` (required) - New deploy key's title
  72 ++ `key` (required) - New deploy key
  73 +
  74 +
  75 +### Delete deploy key
  76 +
  77 +Delete a deploy key from a project
  78 +
  79 +```
  80 +DELETE /projects/:id/keys/:key_id
  81 +```
  82 +
  83 +Parameters:
  84 +
  85 ++ `id` (required) - The ID of the project
  86 ++ `key_id` (required) - The ID of the deploy key
  87 +
doc/api/project_snippets.md 0 → 100644
  Diff comments   View file @68d146b
@@ -0,0 +1,108 @@ @@ -0,0 +1,108 @@
  1 +## List snippets
  2 +
  3 +Get a list of project snippets.
  4 +
  5 +```
  6 +GET /projects/:id/snippets
  7 +```
  8 +
  9 +Parameters:
  10 +
  11 ++ `id` (required) - The ID of a project
  12 +
  13 +
  14 +## Single snippet
  15 +
  16 +Get a single project snippet.
  17 +
  18 +```
  19 +GET /projects/:id/snippets/:snippet_id
  20 +```
  21 +
  22 +Parameters:
  23 +
  24 ++ `id` (required) - The ID of a project
  25 ++ `snippet_id` (required) - The ID of a project's snippet
  26 +
  27 +```json
  28 +{
  29 + "id": 1,
  30 + "title": "test",
  31 + "file_name": "add.rb",
  32 + "author": {
  33 + "id": 1,
  34 + "username": "john_smith",
  35 + "email": "john@example.com",
  36 + "name": "John Smith",
  37 + "blocked": false,
  38 + "created_at": "2012-05-23T08:00:58Z"
  39 + },
  40 + "expires_at": null,
  41 + "updated_at": "2012-06-28T10:52:04Z",
  42 + "created_at": "2012-06-28T10:52:04Z"
  43 +}
  44 +```
  45 +
  46 +
  47 +## Create new snippet
  48 +
  49 +Creates a new project snippet. The user must have permission to create new snippets.
  50 +
  51 +```
  52 +POST /projects/:id/snippets
  53 +```
  54 +
  55 +Parameters:
  56 +
  57 ++ `id` (required) - The ID of a project
  58 ++ `title` (required) - The title of a snippet
  59 ++ `file_name` (required) - The name of a snippet file
  60 ++ `lifetime` (optional) - The expiration date of a snippet
  61 ++ `code` (required) - The content of a snippet
  62 +
  63 +
  64 +## Update snippet
  65 +
  66 +Updates an existing project snippet. The user must have permission to change an existing snippet.
  67 +
  68 +```
  69 +PUT /projects/:id/snippets/:snippet_id
  70 +```
  71 +
  72 +Parameters:
  73 +
  74 ++ `id` (required) - The ID of a project
  75 ++ `snippet_id` (required) - The ID of a project's snippet
  76 ++ `title` (optional) - The title of a snippet
  77 ++ `file_name` (optional) - The name of a snippet file
  78 ++ `lifetime` (optional) - The expiration date of a snippet
  79 ++ `code` (optional) - The content of a snippet
  80 +
  81 +
  82 +## Delete snippet
  83 +
  84 +Deletes an existing project snippet. This is an idempotent function and deleting a non-existent
  85 +snippet still returns a `200 Ok` status code.
  86 +
  87 +```
  88 +DELETE /projects/:id/snippets/:snippet_id
  89 +```
  90 +
  91 +Parameters:
  92 +
  93 ++ `id` (required) - The ID of a project
  94 ++ `snippet_id` (required) - The ID of a project's snippet
  95 +
  96 +
  97 +## Snippet content
  98 +
  99 +Returns the raw project snippet as plain text.
  100 +
  101 +```
  102 +GET /projects/:id/snippets/:snippet_id/raw
  103 +```
  104 +
  105 +Parameters:
  106 +
  107 ++ `id` (required) - The ID of a project
  108 ++ `snippet_id` (required) - The ID of a project's snippet
doc/api/projects.md
  Diff comments   View file @68d146b
@@ -381,126 +381,3 @@ Parameters: @@ -381,126 +381,3 @@ Parameters:
381 + `id` (required) - The ID of the project. 381 + `id` (required) - The ID of the project.
382 + `branch` (required) - The name of the branch. 382 + `branch` (required) - The name of the branch.
383 383
384 -  
385 -### List tags  
386 -  
387 -Lists all tags of a project.  
388 -  
389 -```  
390 -GET /projects/:id/repository/tags  
391 -```  
392 -  
393 -Parameters:  
394 -  
395 -+ `id` (required) - The ID of the project  
396 -  
397 -  
398 -### List commits  
399 -  
400 -Lists all commits with pagination. If the optional `ref_name` name is not given the commits of  
401 -the default branch (usually master) are returned.  
402 -  
403 -```  
404 -GET /projects/:id/repository/commits  
405 -```  
406 -  
407 -Parameters:  
408 -  
409 -+ `id` (required) - The Id of the project  
410 -+ `ref_name` (optional) - The name of a repository branch or tag  
411 -+ `page` (optional) - The page of commits to return (`0` default)  
412 -+ `per_page` (optional) - The number of commits per page (`20` default)  
413 -  
414 -Returns values:  
415 -  
416 -+ `200 Ok` on success and a list with commits  
417 -+ `404 Not Found` if project with id or the branch with `ref_name` not found  
418 -  
419 -  
420 -  
421 -## Deploy Keys  
422 -  
423 -### List deploy keys  
424 -  
425 -Get a list of a project's deploy keys.  
426 -  
427 -```  
428 -GET /projects/:id/keys  
429 -```  
430 -  
431 -Parameters:  
432 -  
433 -+ `id` (required) - The ID of the project  
434 -  
435 -```json  
436 -[  
437 - {  
438 - "id": 1,  
439 - "title" : "Public key"  
440 - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4  
441 - 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4  
442 - soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",  
443 - },  
444 - {  
445 - "id": 3,  
446 - "title" : "Another Public key"  
447 - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4  
448 - 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4  
449 - soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="  
450 - }  
451 -]  
452 -```  
453 -  
454 -  
455 -### Single deploy key  
456 -  
457 -Get a single key.  
458 -  
459 -```  
460 -GET /projects/:id/keys/:key_id  
461 -```  
462 -  
463 -Parameters:  
464 -  
465 -+ `id` (required) - The ID of the project  
466 -+ `key_id` (required) - The ID of the deploy key  
467 -  
468 -```json  
469 -{  
470 - "id": 1,  
471 - "title" : "Public key"  
472 - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4  
473 - 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4  
474 - soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="  
475 -}  
476 -```  
477 -  
478 -  
479 -### Add deploy key  
480 -  
481 -Creates a new deploy key for a project.  
482 -  
483 -```  
484 -POST /projects/:id/keys  
485 -```  
486 -  
487 -Parameters:  
488 -  
489 -+ `id` (required) - The ID of the project  
490 -+ `title` (required) - New deploy key's title  
491 -+ `key` (required) - New deploy key  
492 -  
493 -  
494 -### Delete deploy key  
495 -  
496 -Delete a deploy key from a project  
497 -  
498 -```  
499 -DELETE /projects/:id/keys/:key_id  
500 -```  
501 -  
502 -Parameters:  
503 -  
504 -+ `id` (required) - The ID of the project  
505 -+ `key_id` (required) - The ID of the deploy key  
506 -  
doc/api/snippets.md
View file @b05600f
@@ -1,108 +0,0 @@ @@ -1,108 +0,0 @@
1 -## List snippets  
2 -  
3 -Get a list of project snippets.  
4 -  
5 -```  
6 -GET /projects/:id/snippets  
7 -```  
8 -  
9 -Parameters:  
10 -  
11 -+ `id` (required) - The ID of a project  
12 -  
13 -  
14 -## Single snippet  
15 -  
16 -Get a single project snippet.  
17 -  
18 -```  
19 -GET /projects/:id/snippets/:snippet_id  
20 -```  
21 -  
22 -Parameters:  
23 -  
24 -+ `id` (required) - The ID of a project  
25 -+ `snippet_id` (required) - The ID of a project's snippet  
26 -  
27 -```json  
28 -{  
29 - "id": 1,  
30 - "title": "test",  
31 - "file_name": "add.rb",  
32 - "author": {  
33 - "id": 1,  
34 - "username": "john_smith",  
35 - "email": "john@example.com",  
36 - "name": "John Smith",  
37 - "blocked": false,  
38 - "created_at": "2012-05-23T08:00:58Z"  
39 - },  
40 - "expires_at": null,  
41 - "updated_at": "2012-06-28T10:52:04Z",  
42 - "created_at": "2012-06-28T10:52:04Z"  
43 -}  
44 -```  
45 -  
46 -  
47 -## Create new snippet  
48 -  
49 -Creates a new project snippet. The user must have permission to create new snippets.  
50 -  
51 -```  
52 -POST /projects/:id/snippets  
53 -```  
54 -  
55 -Parameters:  
56 -  
57 -+ `id` (required) - The ID of a project  
58 -+ `title` (required) - The title of a snippet  
59 -+ `file_name` (required) - The name of a snippet file  
60 -+ `lifetime` (optional) - The expiration date of a snippet  
61 -+ `code` (required) - The content of a snippet  
62 -  
63 -  
64 -## Update snippet  
65 -  
66 -Updates an existing project snippet. The user must have permission to change an existing snippet.  
67 -  
68 -```  
69 -PUT /projects/:id/snippets/:snippet_id  
70 -```  
71 -  
72 -Parameters:  
73 -  
74 -+ `id` (required) - The ID of a project  
75 -+ `snippet_id` (required) - The ID of a project's snippet  
76 -+ `title` (optional) - The title of a snippet  
77 -+ `file_name` (optional) - The name of a snippet file  
78 -+ `lifetime` (optional) - The expiration date of a snippet  
79 -+ `code` (optional) - The content of a snippet  
80 -  
81 -  
82 -## Delete snippet  
83 -  
84 -Deletes an existing project snippet. This is an idempotent function and deleting a non-existent  
85 -snippet still returns a `200 Ok` status code.  
86 -  
87 -```  
88 -DELETE /projects/:id/snippets/:snippet_id  
89 -```  
90 -  
91 -Parameters:  
92 -  
93 -+ `id` (required) - The ID of a project  
94 -+ `snippet_id` (required) - The ID of a project's snippet  
95 -  
96 -  
97 -## Snippet content  
98 -  
99 -Returns the raw project snippet as plain text.  
100 -  
101 -```  
102 -GET /projects/:id/snippets/:snippet_id/raw  
103 -```  
104 -  
105 -Parameters:  
106 -  
107 -+ `id` (required) - The ID of a project  
108 -+ `snippet_id` (required) - The ID of a project's snippet