Download as
Browse Code »

Commit 4a60c377b8cd531800757894e26cec1ac649046f

Authored by Sebastian Ziebell
1 parent 33c14636
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

API documentation update for milestones 

Updated the milestones API documentation and added return codes descriptions.
Showing 3 changed files with 48 additions and 25 deletions   Show diff stats
doc/api/milestones.md
  Diff comments   View file @4a60c37
1 1 ## List project milestones
2 2  
3   -Get a list of project milestones.
  3 +Returns a list of project milestones.
4 4  
5 5 ```
6 6 GET /projects/:id/milestones
... ... @@ -10,9 +10,16 @@ Parameters:
10 10  
11 11 + `id` (required) - The ID of a project
12 12  
13   -## Single milestone
  13 +Return values:
14 14  
15   -Get a single project milestone.
  15 ++ `200 Ok` on success and the list of project milestones
  16 ++ `401 Unauthorized` if user is not authenticated
  17 ++ `404 Not Found` if project ID not found
  18 +
  19 +
  20 +## Get single milestone
  21 +
  22 +Gets a single project milestone.
16 23  
17 24 ```
18 25 GET /projects/:id/milestones/:milestone_id
... ... @@ -23,9 +30,16 @@ Parameters:
23 30 + `id` (required) - The ID of a project
24 31 + `milestone_id` (required) - The ID of a project milestone
25 32  
26   -## New milestone
  33 +Return values:
  34 +
  35 ++ `200 Ok` on success and the single milestone
  36 ++ `401 Unauthorized` if user is not authenticated
  37 ++ `404 Not Found` if project ID not found
  38 +
  39 +
  40 +## Create new milestone
27 41  
28   -Create a new project milestone.
  42 +Creates a new project milestone.
29 43  
30 44 ```
31 45 POST /projects/:id/milestones
... ... @@ -38,9 +52,17 @@ Parameters:
38 52 + `description` (optional) - The description of the milestone
39 53 + `due_date` (optional) - The due date of the milestone
40 54  
  55 +Return values:
  56 +
  57 ++ `201 Created` on success and the new milestone
  58 ++ `400 Bad Request` if the required attribute title is not given
  59 ++ `401 Unauthorized` if user is not authenticated
  60 ++ `404 Not Found` if project ID not found
  61 +
  62 +
41 63 ## Edit milestone
42 64  
43   -Update an existing project milestone.
  65 +Updates an existing project milestone.
44 66  
45 67 ```
46 68 PUT /projects/:id/milestones/:milestone_id
... ... @@ -54,3 +76,9 @@ Parameters:
54 76 + `description` (optional) - The description of a milestone
55 77 + `due_date` (optional) - The due date of the milestone
56 78 + `closed` (optional) - The status of the milestone
  79 +
  80 +Return values:
  81 +
  82 ++ `200 Ok` on success and the updated milestone
  83 ++ `401 Unauthorized` if user is not authenticated
  84 ++ `404 Not Found` if project ID or milestone ID not found
... ...
lib/api/milestones.rb
  Diff comments   View file @4a60c37
... ... @@ -4,20 +4,6 @@ module Gitlab
4 4 before { authenticate! }
5 5  
6 6 resource :projects do
7   -
8   - helpers do
9   - # If an error occurs this helper method handles error codes for a given milestone
10   - #
11   - # Parameters:
12   - # milestone_errors (required) - The erros collection of a milestone
13   - #
14   - def handle_milestone_errors(milestone_errors)
15   - if milestone_errors[:title].any?
16   - bad_request!(:title)
17   - end
18   - end
19   - end
20   -
21 7 # Get a list of project milestones
22 8 #
23 9 # Parameters:
... ... @@ -56,12 +42,13 @@ module Gitlab
56 42 post ":id/milestones" do
57 43 authorize! :admin_milestone, user_project
58 44  
  45 + bad_request!(:title) unless params[:title].present?
  46 +
59 47 attrs = attributes_for_keys [:title, :description, :due_date]
60 48 @milestone = user_project.milestones.new attrs
61 49 if @milestone.save
62 50 present @milestone, with: Entities::Milestone
63 51 else
64   - handle_milestone_errors(@milestone.errors)
65 52 not_found!
66 53 end
67 54 end
... ... @@ -85,7 +72,6 @@ module Gitlab
85 72 if @milestone.update_attributes attrs
86 73 present @milestone, with: Entities::Milestone
87 74 else
88   - handle_milestone_errors(@milestone.errors)
89 75 not_found!
90 76 end
91 77 end
... ...
spec/requests/api/milestones_spec.rb
  Diff comments   View file @4a60c37
... ... @@ -16,6 +16,11 @@ describe Gitlab::API do
16 16 json_response.should be_an Array
17 17 json_response.first['title'].should == milestone.title
18 18 end
  19 +
  20 + it "should return a 401 error if user not authenticated" do
  21 + get api("/projects/#{project.id}/milestones")
  22 + response.status.should == 401
  23 + end
19 24 end
20 25  
21 26 describe "GET /projects/:id/milestones/:milestone_id" do
... ... @@ -25,6 +30,11 @@ describe Gitlab::API do
25 30 json_response['title'].should == milestone.title
26 31 end
27 32  
  33 + it "should return 401 error if user not authenticated" do
  34 + get api("/projects/#{project.id}/milestones/#{milestone.id}")
  35 + response.status.should == 401
  36 + end
  37 +
28 38 it "should return a 404 error if milestone id not found" do
29 39 get api("/projects/#{project.id}/milestones/1234", user)
30 40 response.status.should == 404
... ... @@ -33,8 +43,7 @@ describe Gitlab::API do
33 43  
34 44 describe "POST /projects/:id/milestones" do
35 45 it "should create a new project milestone" do
36   - post api("/projects/#{project.id}/milestones", user),
37   - title: 'new milestone'
  46 + post api("/projects/#{project.id}/milestones", user), title: 'new milestone'
38 47 response.status.should == 201
39 48 json_response['title'].should == 'new milestone'
40 49 json_response['description'].should be_nil
... ... @@ -62,7 +71,7 @@ describe Gitlab::API do
62 71 json_response['title'].should == 'updated title'
63 72 end
64 73  
65   - it "should return a 404 error if milestone is not found" do
  74 + it "should return a 404 error if milestone id not found" do
66 75 put api("/projects/#{project.id}/milestones/1234", user),
67 76 title: 'updated title'
68 77 response.status.should == 404
... ...