API documentation update for milestones

Updated the milestones API documentation and added return codes descriptions.

API documentation update for milestones
Updated the milestones API documentation and added return codes descriptions.
Sebastian Ziebell
1 parent 33c14636
Showing 3 changed files with 48 additions and 25 deletions Show diff stats
doc/api/milestones.md
lib/api/milestones.rb
spec/requests/api/milestones_spec.rb
 ## List project milestones
-Get a list of project milestones.
+Returns a list of project milestones.
 ```
 GET /projects/:id/milestones
@@ -10,9 +10,16 @@ Parameters:
 + `id` (required) - The ID of a project
-## Single milestone
+Return values:
-Get a single project milestone.
++ `200 Ok` on success and the list of project milestones
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
+## Get single milestone
+
+Gets a single project milestone.
 ```
 GET /projects/:id/milestones/:milestone_id
@@ -23,9 +30,16 @@ Parameters:
 + `id` (required) - The ID of a project
 + `milestone_id` (required) - The ID of a project milestone
-## New milestone
+Return values:
+
++ `200 Ok` on success and the single milestone
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
+## Create new milestone
-Create a new project milestone.
+Creates a new project milestone.
 ```
 POST /projects/:id/milestones
@@ -38,9 +52,17 @@ Parameters:
 + `description` (optional) - The description of the milestone
 + `due_date` (optional) - The due date of the milestone
+Return values:
+
++ `201 Created` on success and the new milestone
++ `400 Bad Request` if the required attribute title is not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
 ## Edit milestone
-Update an existing project milestone.
+Updates an existing project milestone.
 ```
 PUT /projects/:id/milestones/:milestone_id
@@ -54,3 +76,9 @@ Parameters:
 + `description` (optional) - The description of a milestone
 + `due_date` (optional) - The due date of the milestone
 + `closed` (optional) - The status of the milestone
+
+Return values:
+
++ `200 Ok` on success and the updated milestone
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or milestone ID not found
@@ -4,20 +4,6 @@ module Gitlab
     before { authenticate! }
     resource :projects do
-
-      helpers do
-        # If an error occurs this helper method handles error codes for a given milestone
-        #
-        # Parameters:
-        #   milestone_errors (required) - The erros collection of a milestone
-        #
-        def handle_milestone_errors(milestone_errors)
-          if milestone_errors[:title].any?
-            bad_request!(:title)
-          end
-        end
-      end
-
       # Get a list of project milestones
       #
       # Parameters:
@@ -56,12 +42,13 @@ module Gitlab
       post ":id/milestones" do
         authorize! :admin_milestone, user_project
+        bad_request!(:title) unless params[:title].present?
+
         attrs = attributes_for_keys [:title, :description, :due_date]
         @milestone = user_project.milestones.new attrs
         if @milestone.save
           present @milestone, with: Entities::Milestone
         else
-          handle_milestone_errors(@milestone.errors)
           not_found!
         end
       end
@@ -85,7 +72,6 @@ module Gitlab
         if @milestone.update_attributes attrs
           present @milestone, with: Entities::Milestone
         else
-          handle_milestone_errors(@milestone.errors)
           not_found!
         end
       end
@@ -16,6 +16,11 @@ describe Gitlab::API do
       json_response.should be_an Array
       json_response.first['title'].should == milestone.title
     end
+
+    it "should return a 401 error if user not authenticated" do
+      get api("/projects/#{project.id}/milestones")
+      response.status.should == 401
+    end
   end
   describe "GET /projects/:id/milestones/:milestone_id" do
@@ -25,6 +30,11 @@ describe Gitlab::API do
       json_response['title'].should == milestone.title
     end
+    it "should return 401 error if user not authenticated" do
+      get api("/projects/#{project.id}/milestones/#{milestone.id}")
+      response.status.should == 401
+    end
+
     it "should return a 404 error if milestone id not found" do
       get api("/projects/#{project.id}/milestones/1234", user)
       response.status.should == 404
@@ -33,8 +43,7 @@ describe Gitlab::API do
   describe "POST /projects/:id/milestones" do
     it "should create a new project milestone" do
-      post api("/projects/#{project.id}/milestones", user),
-        title: 'new milestone'
+      post api("/projects/#{project.id}/milestones", user), title: 'new milestone'
       response.status.should == 201
       json_response['title'].should == 'new milestone'
       json_response['description'].should be_nil
@@ -62,7 +71,7 @@ describe Gitlab::API do
       json_response['title'].should == 'updated title'
     end
-    it "should return a 404 error if milestone is not found" do
+    it "should return a 404 error if milestone id not found" do
       put api("/projects/#{project.id}/milestones/1234", user),
         title: 'updated title'
       response.status.should == 404