API documentation update for milestones

Updated the milestones API documentation and added return codes descriptions.

doc/api/milestones.md

@@ -1,6 +1,6 @@
 ## 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:
 
-Create a new project milestone.
++ `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
+
+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

lib/api/milestones.rb

@@ -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

spec/requests/api/milestones_spec.rb

@@ -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