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 1 class HelpController < ApplicationController
2 2 def index
3 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 15 end
... ...
app/views/help/_api_layout.html.haml 0 → 100644
  Diff comments   View file @68d146b
... ... @@ -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 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 29 #
30 30 get 'help' => 'help#index'
31 31 get 'help/api' => 'help#api'
  32 + get 'help/api/:category' => 'help#api', as: 'help_api_file'
32 33 get 'help/markdown' => 'help#markdown'
33 34 get 'help/permissions' => 'help#permissions'
34 35 get 'help/public_access' => 'help#public_access'
... ...
doc/api/deploy_keys.md 0 → 100644
  Diff comments   View file @68d146b
... ... @@ -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 @@
  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 381 + `id` (required) - The ID of the project.
382 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   -## 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