Merge branch 'grapify-groups-api' into 'master'

Grapify the group API

## What are the relevant issue numbers?

Related to #22928

See merge request !7359

lib/api/groups.rb

 module API
-  # groups API
   class Groups < Grape::API
     before { authenticate! }
 
+    helpers do
+      params :optional_params do
+        optional :description, type: String, desc: 'The description of the group'
+        optional :visibility_level, type: Integer, desc: 'The visibility level of the group'
+        optional :lfs_enabled, type: Boolean, desc: 'Enable/disable LFS for the projects in this group'
+        optional :request_access_enabled, type: Boolean, desc: 'Allow users to request member access'
+      end
+    end
+
     resource :groups do
-      # Get a groups list
-      #
-      # Parameters:
-      #   skip_groups (optional) - Array of group ids to exclude from list
-      #   all_available (optional, boolean) - Show all group that you have access to
-      # Example Request:
-      #  GET /groups
+      desc 'Get a groups list' do
+        success Entities::Group
+      end
+      params do
+        optional :skip_groups, type: Array[Integer], desc: 'Array of group ids to exclude from list'
+        optional :all_available, type: Boolean, desc: 'Show all group that you have access to'
+        optional :search, type: String, desc: 'Search for a specific group'
+      end
       get do
-        @groups = if current_user.admin
+        groups = if current_user.admin
                    Group.all
                  elsif params[:all_available]
                    GroupsFinder.new.execute(current_user)
@@ -20,99 +29,83 @@ module API
                    current_user.groups
                  end
 
-        @groups = @groups.search(params[:search]) if params[:search].present?
-        @groups = @groups.where.not(id: params[:skip_groups]) if params[:skip_groups].present?
-        @groups = paginate @groups
-        present @groups, with: Entities::Group
+        groups = groups.search(params[:search]) if params[:search].present?
+        groups = groups.where.not(id: params[:skip_groups]) if params[:skip_groups].present?
+        present paginate(groups), with: Entities::Group
       end
 
-      # Get list of owned groups for authenticated user
-      #
-      # Example Request:
-      #   GET /groups/owned
+      desc 'Get list of owned groups for authenticated user' do
+        success Entities::Group
+      end
       get '/owned' do
-        @groups = current_user.owned_groups
-        @groups = paginate @groups
-        present @groups, with: Entities::Group, user: current_user
+        groups = current_user.owned_groups
+        present paginate(groups), with: Entities::Group, user: current_user
       end
 
-      # Create group. Available only for users who can create groups.
-      #
-      # Parameters:
-      #   name (required)                   - The name of the group
-      #   path (required)                   - The path of the group
-      #   description (optional)            - The description of the group
-      #   visibility_level (optional)       - The visibility level of the group
-      #   lfs_enabled (optional)            - Enable/disable LFS for the projects in this group
-      #   request_access_enabled (optional) - Allow users to request member access
-      # Example Request:
-      #   POST /groups
+      desc 'Create a group. Available only for users who can create groups.' do
+        success Entities::Group
+      end
+      params do
+        requires :name, type: String, desc: 'The name of the group'
+        requires :path, type: String, desc: 'The path of the group'
+        use :optional_params
+      end
       post do
         authorize! :create_group
-        required_attributes! [:name, :path]
 
-        attrs = attributes_for_keys [:name, :path, :description, :visibility_level, :lfs_enabled, :request_access_enabled]
-        @group = Group.new(attrs)
+        group = ::Groups::CreateService.new(current_user, declared_params(include_missing: false)).execute
 
-        if @group.save
-          @group.add_owner(current_user)
-          present @group, with: Entities::Group
+        if group.persisted?
+          present group, with: Entities::Group
         else
-          render_api_error!("Failed to save group #{@group.errors.messages}", 400)
+          render_api_error!("Failed to save group #{group.errors.messages}", 400)
+        end
       end
     end
 
-      # Update group. Available only for users who can administrate groups.
-      #
-      # Parameters:
-      #   id (required)                     - The ID of a group
-      #   path (optional)                   - The path of the group
-      #   description (optional)            - The description of the group
-      #   visibility_level (optional)       - The visibility level of the group
-      #   lfs_enabled (optional)            - Enable/disable LFS for the projects in this group
-      #   request_access_enabled (optional) - Allow users to request member access
-      # Example Request:
-      #   PUT /groups/:id
+    params do
+      requires :id, type: String, desc: 'The ID of a group'
+    end
+    resource :groups do
+      desc 'Update a group. Available only for users who can administrate groups.' do
+        success Entities::Group
+      end
+      params do
+        optional :name, type: String, desc: 'The name of the group'
+        optional :path, type: String, desc: 'The path of the group'
+        use :optional_params
+        at_least_one_of :name, :path, :description, :visibility_level,
+                        :lfs_enabled, :request_access_enabled
+      end
       put ':id' do
         group = find_group(params[:id])
         authorize! :admin_group, group
 
-        attrs = attributes_for_keys [:name, :path, :description, :visibility_level, :lfs_enabled, :request_access_enabled]
-
-        if ::Groups::UpdateService.new(group, current_user, attrs).execute
+        if ::Groups::UpdateService.new(group, current_user, declared_params(include_missing: false)).execute
           present group, with: Entities::GroupDetail
         else
           render_validation_error!(group)
         end
       end
 
-      # Get a single group, with containing projects
-      #
-      # Parameters:
-      #   id (required) - The ID of a group
-      # Example Request:
-      #   GET /groups/:id
+      desc 'Get a single group, with containing projects.' do
+        success Entities::GroupDetail
+      end
       get ":id" do
         group = find_group(params[:id])
         present group, with: Entities::GroupDetail
       end
 
-      # Remove group
-      #
-      # Parameters:
-      #   id (required) - The ID of a group
-      # Example Request:
-      #   DELETE /groups/:id
+      desc 'Remove a group.'
       delete ":id" do
         group = find_group(params[:id])
         authorize! :admin_group, group
         DestroyGroupService.new(group, current_user).execute
       end
 
-      # Get a list of projects in this group
-      #
-      # Example Request:
-      #   GET /groups/:id/projects
+      desc 'Get a list of projects in this group.' do
+        success Entities::Project
+      end
       get ":id/projects" do
         group = find_group(params[:id])
         projects = GroupProjectsFinder.new(group).execute(current_user)
@@ -120,13 +113,12 @@ module API
         present projects, with: Entities::Project, user: current_user
       end
 
-      # Transfer a project to the Group namespace
-      #
-      # Parameters:
-      #   id - group id
-      #   project_id  - project id
-      # Example Request:
-      #   POST /groups/:id/projects/:project_id
+      desc 'Transfer a project to the group namespace. Available only for admin.' do
+        success Entities::GroupDetail
+      end
+      params do
+        requires :project_id, type: String, desc: 'The ID of the project'
+      end
       post ":id/projects/:project_id" do
         authenticated_as_admin!
         group = Group.find_by(id: params[:id])
@@ -134,7 +126,7 @@ module API
         result = ::Projects::TransferService.new(project, current_user).execute(group)
 
         if result
-          present group
+          present group, with: Entities::GroupDetail
         else
           render_api_error!("Failed to transfer project #{project.errors.messages}", 400)
         end

spec/requests/api/groups_spec.rb

@@ -167,7 +167,7 @@ describe API::API, api: true  do
       end
 
       it 'returns 404 for a non existing group' do
-        put api('/groups/1328', user1)
+        put api('/groups/1328', user1), name: new_group_name
 
         expect(response).to have_http_status(404)
       end