API: groups documentation updated, functions return different status codes

Updates the API documentation of groups with infos to return codes. The function calls
in the groups API have updated documentation and return `400 Bad Request` status code
if a required attribute is missing.

doc/api/groups.md

@@ -17,7 +17,14 @@ GET /groups
 ]
 ```
 
-## Details of group
+Return values:
+
++ `200 Ok` on success and list of groups
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something fails
+
+
+## Details of a group
 
 Get all details of a group.
 
@@ -29,17 +36,30 @@ Parameters:
 
 + `id` (required) - The ID of a group
 
+Return values:
+
++ `200 Ok` on success and the details of a group
++ `401 Unauthorized` if user not authenticated
++ `404 Not Found` if group ID not found
+
+
 ## New group
 
-Create a new project group. Available only for admin
+Creates a new project group. Available only for admin.
 
 ```
 POST /groups
 ```
 
 Parameters:
-+ `name` (required)                  - Email
-+ `path`                             - Password
 
-Will return created group with status `201 Created` on success, or `404 Not found` on fail.
++ `name` (required) - The name of the group
++ `path` (required) - The path of the group
+
+Return valueS:
+
++ `201 Created` on success and the newly created group
++ `400 Bad Request` if one of the required attributes not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something fails
 

lib/api/groups.rb

@@ -6,6 +6,9 @@ module Gitlab
     resource :groups do
       # Get a groups list
       #
+      # Parameters
+      #   page (optional) - The page number of the groups list
+      #   per_page (optional) - The number of elements per page
       # Example Request:
       #  GET /groups
       get do
@@ -20,12 +23,16 @@ module Gitlab
       # Create group. Available only for admin
       #
       # Parameters:
-      #   name (required)                   - Name
-      #   path (required)                   - Path
+      #   name (required) - The name of the group
+      #   path (required) - The path of the group
       # Example Request:
       #   POST /groups
       post do
         authenticated_as_admin!
+
+        bad_request!(:name) unless params[:name].present?
+        bad_request!(:path) unless params[:path].present?
+
         attrs = attributes_for_keys [:name, :path]
         @group = Group.new(attrs)
         @group.owner = current_user

spec/requests/api/groups_spec.rb

@@ -88,6 +88,16 @@ describe Gitlab::API do
         post api("/groups", admin), {:name => "Duplicate Test", :path => group2.path}
         response.status.should == 404
       end
+
+      it "should return 400 bad request error if name not given" do
+        post api("/groups", admin), { :path => group2.path }
+        response.status.should == 400
+      end
+
+      it "should return 400 bad request error if path not given" do
+        post api("/groups", admin), { :name => 'test' }
+        response.status.should == 400
+      end
     end
   end
 end