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.

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.
Sebastian Ziebell
1 parent e96d77d3
Showing 4 changed files with 59 additions and 13 deletions Show diff stats
doc/api/issues.md
doc/api/merge_requests.md
lib/api/merge_requests.rb
spec/requests/api/merge_requests_spec.rb
 ## 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
 ## 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
@@ -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
@@ -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"
1	1	## List issues
2	2
3	3	Get all issues created by authenticed user. This function takes pagination parameters
4		-`page` and `per_page` to get a list of issues.
	4	+`page` and `per_page` to restrict the list of issues.
5	5
6	6	```
7	7	GET /issues
...	...
1	1	## List merge requests
2	2
3		-Get all MR for this project.
	3	+Get all merge requests for this project. This function takes pagination parameters
	4	+`page` and `per_page` to restrict the list of merge requests.
4	5
5	6	```
6	7	GET /projects/:id/merge_requests
...	...	@@ -40,9 +41,16 @@ Parameters:
40	41	]
41	42	```
42	43
43		-## Show MR
	44	+Return values:
44	45
45		-Show information about MR.
	46	++ `200 Ok` on success and the list of merge requests
	47	++ `401 Unauthorized` if user is not authenticated
	48	++ `404 Not Found` if project ID not found
	49	+
	50	+
	51	+## Get single MR
	52	+
	53	+Shows information about a single merge request.
46	54
47	55	```
48	56	GET /projects/:id/merge_request/:merge_request_id
...	...	@@ -81,10 +89,16 @@ Parameters:
81	89	}
82	90	```
83	91
	92	+Return values:
	93	+
	94	++ `200 Ok` on success and the single merge request
	95	++ `401 Unauthorized` if user is not authenticated
	96	++ `404 Not Found` if project ID or merge request ID not found
	97	+
84	98
85	99	## Create MR
86	100
87		-Create MR.
	101	+Creates a new merge request.
88	102
89	103	```
90	104	POST /projects/:id/merge_requests
...	...	@@ -126,9 +140,18 @@ Parameters:
126	140	}
127	141	```
128	142
	143	+Return values:
	144	+
	145	++ `201 Created` on success and the created merge request
	146	++ `400 Bad Request` if one of the required attributes is missing
	147	++ `401 Unauthorize` if user is not authenticated or not allowed
	148	++ `403 Forbidden` if user is not allowed to create a merge request
	149	++ `404 Not Found` if project ID not found or something else fails
	150	+
	151	+
129	152	## Update MR
130	153
131		-Update MR. You can change branches, title, or even close the MR.
	154	+Updates an existing merge request. You can change branches, title, or even close the MR.
132	155
133	156	```
134	157	PUT /projects/:id/merge_request/:merge_request_id
...	...	@@ -172,9 +195,18 @@ Parameters:
172	195	}
173	196	}
174	197	```
	198	+
	199	+Return values:
	200	+
	201	++ `200 Ok` on success and the updated merge request
	202	++ `401 Unauthorize` if user is not authenticated or not allowed
	203	++ `403 Forbidden` if user is not allowed to update the merge request
	204	++ `404 Not Found` if project ID or merge request ID not found
	205	+
	206	+
175	207	## Post comment to MR
176	208
177		-Post comment to MR
	209	+Adds a comment to a merge request.
178	210
179	211	```
180	212	POST /projects/:id/merge_request/:merge_request_id/comments
...	...	@@ -183,10 +215,9 @@ POST /projects/:id/merge_request/:merge_request_id/comments
183	215	Parameters:
184	216
185	217	+ `id` (required) - The ID of a project
186		-+ `merge_request_id` (required) - ID of MR
	218	++ `merge_request_id` (required) - ID of merge request
187	219	+ `note` (required) - Text of comment
188	220
189		-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
190	221
191	222	```json
192	223	{
...	...	@@ -201,3 +232,10 @@ Will return created note with status `201 Created` on success, or `404 Not found
201	232	"note":"text1"
202	233	}
203	234	```
	235	+
	236	+Return values:
	237	+
	238	++ `201 Created` on success and the new comment
	239	++ `400 Bad Request` if the required attribute note is not given
	240	++ `401 Unauthorized` if user is not authenticated
	241	++ `404 Not Found` if project ID or merge request ID not found
...	...
...	...	@@ -69,6 +69,10 @@ module Gitlab
69	69	post ":id/merge_requests" do
70	70	authorize! :write_merge_request, user_project
71	71
	72	+ bad_request!(:source_branch) unless params[:source_branch].present?
	73	+ bad_request!(:target_branch) unless params[:target_branch].present?
	74	+ bad_request!(:title) unless params[:title].present?
	75	+
72	76	attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title]
73	77	merge_request = user_project.merge_requests.new(attrs)
74	78	merge_request.author = current_user
...	...	@@ -121,6 +125,8 @@ module Gitlab
121	125	# POST /projects/:id/merge_request/:merge_request_id/comments
122	126	#
123	127	post ":id/merge_request/:merge_request_id/comments" do
	128	+ bad_request!(:note) unless params[:note].present?
	129	+
124	130	merge_request = user_project.merge_requests.find(params[:merge_request_id])
125	131	note = merge_request.notes.new(note: params[:note], project_id: user_project.id)
126	132	note.author = current_user
...	...	@@ -128,9 +134,6 @@ module Gitlab
128	134	if note.save
129	135	present note, with: Entities::MRNote
130	136	else
131		- if note.errors[:note].any?
132		- bad_request!(:note)
133		- end
134	137	not_found!
135	138	end
136	139	end
...	...
...	...	@@ -64,6 +64,12 @@ describe Gitlab::API do
64	64	title: "Test merge_request", source_branch: "stable", author: user
65	65	response.status.should == 400
66	66	end
	67	+
	68	+ it "should return 400 when title is missing" do
	69	+ post api("/projects/#{project.id}/merge_requests", user),
	70	+ target_branch: 'master', source_branch: 'stable'
	71	+ response.status.should == 400
	72	+ end
67	73	end
68	74
69	75	describe "PUT /projects/:id/merge_request/:merge_request_id to close MR" do
...	...	@@ -82,7 +88,6 @@ describe Gitlab::API do
82	88	end
83	89	end
84	90
85		-
86	91	describe "PUT /projects/:id/merge_request/:merge_request_id" do
87	92	it "should return merge_request" do
88	93	put api("/projects/#{project.id}/merge_request/#{merge_request.id}", user), title: "New title"
...	...