API: merge request documentation updated, added return codes to functions

The API documentation of merge requests contains info to status codes for all functions.
Required arguments are now checked in the merge requests API functions and a `400 Bad Request` error is
returned if they are not given.

doc/api/issues.md

@@ -1,7 +1,7 @@
 ## List issues
 
 Get all issues created by authenticed user. This function takes pagination parameters
-`page` and `per_page` to get a list of issues.
+`page` and `per_page` to restrict the list of issues.
 
 ```
 GET /issues

doc/api/merge_requests.md

@@ -1,6 +1,7 @@
 ## List merge requests
 
-Get all MR for this project.
+Get all merge requests for this project. This function takes pagination parameters
+`page` and `per_page` to restrict the list of merge requests.
 
 ```
 GET /projects/:id/merge_requests
@@ -40,9 +41,16 @@ Parameters:
 ]
 ```
 
-## Show MR
+Return values:
 
-Show information about MR.
++ `200 Ok` on success and the list of merge requests
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
+## Get single MR
+
+Shows information about a single merge request.
 
 ```
 GET /projects/:id/merge_request/:merge_request_id
@@ -81,10 +89,16 @@ Parameters:
 }
 ```
 
+Return values:
+
++ `200 Ok` on success and the single merge request
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or merge request ID not found
+
 
 ## Create MR
 
-Create MR.
+Creates a new merge request.
 
 ```
 POST /projects/:id/merge_requests
@@ -126,9 +140,18 @@ Parameters:
 }
 ```
 
+Return values:
+
++ `201 Created` on success and the created merge request
++ `400 Bad Request` if one of the required attributes is missing
++ `401 Unauthorize` if user is not authenticated or not allowed
++ `403 Forbidden` if user is not allowed to create a merge request
++ `404 Not Found` if project ID not found or something else fails
+
+
 ## Update MR
 
-Update MR. You can change branches, title, or even close the MR.
+Updates an existing merge request. You can change branches, title, or even close the MR.
 
 ```
 PUT /projects/:id/merge_request/:merge_request_id
@@ -172,9 +195,18 @@ Parameters:
     }
 }
 ```
+
+Return values:
+
++ `200 Ok` on success and the updated merge request
++ `401 Unauthorize` if user is not authenticated or not allowed
++ `403 Forbidden` if user is not allowed to update the merge request
++ `404 Not Found` if project ID or merge request ID not found
+
+
 ## Post comment to MR
 
-Post comment to MR
+Adds a comment to a merge request.
 
 ```
 POST /projects/:id/merge_request/:merge_request_id/comments
@@ -183,10 +215,9 @@ POST /projects/:id/merge_request/:merge_request_id/comments
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `merge_request_id` (required) - ID of MR
++ `merge_request_id` (required) - ID of merge request
 + `note` (required) - Text of comment
 
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
 
 ```json
 {
@@ -201,3 +232,10 @@ Will return created note with status `201 Created` on success, or `404 Not found
     "note":"text1"
 }
 ```
+
+Return values:
+
++ `201 Created` on success and the new comment
++ `400 Bad Request` if the required attribute note is not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or merge request ID not found

lib/api/merge_requests.rb

@@ -69,6 +69,10 @@ module Gitlab
       post ":id/merge_requests" do
         authorize! :write_merge_request, user_project
 
+        bad_request!(:source_branch) unless params[:source_branch].present?
+        bad_request!(:target_branch) unless params[:target_branch].present?
+        bad_request!(:title) unless params[:title].present?
+
         attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title]
         merge_request = user_project.merge_requests.new(attrs)
         merge_request.author = current_user
@@ -121,6 +125,8 @@ module Gitlab
       #   POST /projects/:id/merge_request/:merge_request_id/comments
       #
       post ":id/merge_request/:merge_request_id/comments" do
+        bad_request!(:note) unless params[:note].present?
+
         merge_request = user_project.merge_requests.find(params[:merge_request_id])
         note = merge_request.notes.new(note: params[:note], project_id: user_project.id)
         note.author = current_user
@@ -128,9 +134,6 @@ module Gitlab
         if note.save
           present note, with: Entities::MRNote
         else
-          if note.errors[:note].any?
-            bad_request!(:note)
-          end
           not_found!
         end
       end

spec/requests/api/merge_requests_spec.rb

@@ -64,6 +64,12 @@ describe Gitlab::API do
         title: "Test merge_request", source_branch: "stable", author: user
       response.status.should == 400
     end
+
+    it "should return 400 when title is missing" do
+      post api("/projects/#{project.id}/merge_requests", user),
+        target_branch: 'master', source_branch: 'stable'
+      response.status.should == 400
+    end
   end
 
   describe "PUT /projects/:id/merge_request/:merge_request_id to close MR" do
@@ -82,7 +88,6 @@ describe Gitlab::API do
     end
   end
 
-
   describe "PUT /projects/:id/merge_request/:merge_request_id" do
     it "should return merge_request" do
       put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user), title: "New title"