diff --git a/lib/api/branches.rb b/lib/api/branches.rb
index 6d8274489945ec02b88cb55356a35bc468ab6781..21a106387f083ff748ffaf57b8fc3cb4f8e7b070 100644
--- a/lib/api/branches.rb
+++ b/lib/api/branches.rb
@@ -6,58 +6,55 @@ module API
     before { authenticate! }
     before { authorize! :download_code, user_project }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
-      # Get a project repository branches
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      # Example Request:
-      #   GET /projects/:id/repository/branches
+      desc 'Get a project repository branches' do
+        success Entities::RepoBranch
+      end
       get ":id/repository/branches" do
         branches = user_project.repository.branches.sort_by(&:name)
 
         present branches, with: Entities::RepoBranch, project: user_project
       end
 
-      # Get a single branch
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   branch (required) - The name of the branch
-      # Example Request:
-      #   GET /projects/:id/repository/branches/:branch
-      get ':id/repository/branches/:branch', requirements: { branch: /.+/ } do
-        @branch = user_project.repository.branches.find { |item| item.name == params[:branch] }
-        not_found!("Branch") unless @branch
+      desc 'Get a single branch' do
+        success Entities::RepoBranch
+      end
+      params do
+        requires :branch, type: String, regexp: /.+/, desc: 'The name of the branch'
+      end
+      get ':id/repository/branches/:branch' do
+        branch = user_project.repository.find_branch(params[:branch])
+        not_found!("Branch") unless branch
 
-        present @branch, with: Entities::RepoBranch, project: user_project
+        present branch, with: Entities::RepoBranch, project: user_project
       end
 
-      # Protect a single branch
-      #
       # Note: The internal data model moved from `developers_can_{merge,push}` to `allowed_to_{merge,push}`
       # in `gitlab-org/gitlab-ce!5081`. The API interface has not been changed (to maintain compatibility),
       # but it works with the changed data model to infer `developers_can_merge` and `developers_can_push`.
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   branch (required) - The name of the branch
-      #   developers_can_push (optional) - Flag if developers can push to that branch
-      #   developers_can_merge (optional) - Flag if developers can merge to that branch
-      # Example Request:
-      #   PUT /projects/:id/repository/branches/:branch/protect
-      put ':id/repository/branches/:branch/protect',
-          requirements: { branch: /.+/ } do
+      desc 'Protect a single branch' do
+        success Entities::RepoBranch
+      end
+      params do
+        requires :branch, type: String, regexp: /.+/, desc: 'The name of the branch'
+        optional :developers_can_push, type: Boolean, desc: 'Flag if developers can push to that branch'
+        optional :developers_can_merge, type: Boolean, desc: 'Flag if developers can merge to that branch'
+      end
+      put ':id/repository/branches/:branch/protect' do
         authorize_admin_project
 
-        @branch = user_project.repository.find_branch(params[:branch])
-        not_found!('Branch') unless @branch
-        protected_branch = user_project.protected_branches.find_by(name: @branch.name)
+        branch = user_project.repository.find_branch(params[:branch])
+        not_found!('Branch') unless branch
+
+        protected_branch = user_project.protected_branches.find_by(name: branch.name)
 
         protected_branch_params = {
-          name: @branch.name,
-          developers_can_push: to_boolean(params[:developers_can_push]),
-          developers_can_merge: to_boolean(params[:developers_can_merge])
+          name: branch.name,
+          developers_can_push: params[:developers_can_push],
+          developers_can_merge: params[:developers_can_merge]
         }
 
         service_args = [user_project, current_user, protected_branch_params]
@@ -69,39 +66,36 @@ module API
                            end
 
         if protected_branch.valid?
-          present @branch, with: Entities::RepoBranch, project: user_project
+          present branch, with: Entities::RepoBranch, project: user_project
         else
           render_api_error!(protected_branch.errors.full_messages, 422)
         end
       end
 
-      # Unprotect a single branch
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   branch (required) - The name of the branch
-      # Example Request:
-      #   PUT /projects/:id/repository/branches/:branch/unprotect
-      put ':id/repository/branches/:branch/unprotect',
-          requirements: { branch: /.+/ } do
+      desc 'Unprotect a single branch' do
+        success Entities::RepoBranch
+      end
+      params do
+        requires :branch, type: String, regexp: /.+/, desc: 'The name of the branch'
+      end
+      put ':id/repository/branches/:branch/unprotect' do
         authorize_admin_project
 
-        @branch = user_project.repository.find_branch(params[:branch])
-        not_found!("Branch") unless @branch
-        protected_branch = user_project.protected_branches.find_by(name: @branch.name)
+        branch = user_project.repository.find_branch(params[:branch])
+        not_found!("Branch") unless branch
+        protected_branch = user_project.protected_branches.find_by(name: branch.name)
         protected_branch.destroy if protected_branch
 
-        present @branch, with: Entities::RepoBranch, project: user_project
+        present branch, with: Entities::RepoBranch, project: user_project
       end
 
-      # Create branch
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   branch_name (required) - The name of the branch
-      #   ref (required) - Create branch from commit sha or existing branch
-      # Example Request:
-      #   POST /projects/:id/repository/branches
+      desc 'Create branch' do
+        success Entities::RepoBranch
+      end
+      params do
+        requires :branch_name, type: String, desc: 'The name of the branch'
+        requires :ref, type: String, desc: 'Create branch from commit sha or existing branch'
+      end
       post ":id/repository/branches" do
         authorize_push_project
         result = CreateBranchService.new(user_project, current_user).
@@ -116,16 +110,13 @@ module API
         end
       end
 
-      # Delete branch
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   branch (required) - The name of the branch
-      # Example Request:
-      #   DELETE /projects/:id/repository/branches/:branch
-      delete ":id/repository/branches/:branch",
-             requirements: { branch: /.+/ } do
+      desc 'Delete a branch'
+      params do
+        requires :branch, type: String, regexp: /.+/, desc: 'The name of the branch'
+      end
+      delete ":id/repository/branches/:branch" do
         authorize_push_project
+
         result = DeleteBranchService.new(user_project, current_user).
                  execute(params[:branch])
 
diff --git a/spec/requests/api/branches_spec.rb b/spec/requests/api/branches_spec.rb
index 905f762d578c85d66b7e9f9d1b9d982e0de93cae..1711096f4bd4a6101fe5ae229b6a4b29d56a92d7 100644
--- a/spec/requests/api/branches_spec.rb
+++ b/spec/requests/api/branches_spec.rb
@@ -95,18 +95,6 @@ describe API::API, api: true  do
         expect(json_response['developers_can_push']).to eq(true)
         expect(json_response['developers_can_merge']).to eq(true)
       end
-
-      it 'protects a single branch and developers cannot push and merge' do
-        put api("/projects/#{project.id}/repository/branches/#{branch_name}/protect", user),
-            developers_can_push: 'tru', developers_can_merge: 'tr'
-
-        expect(response).to have_http_status(200)
-        expect(json_response['name']).to eq(branch_name)
-        expect(json_response['commit']['id']).to eq(branch_sha)
-        expect(json_response['protected']).to eq(true)
-        expect(json_response['developers_can_push']).to eq(false)
-        expect(json_response['developers_can_merge']).to eq(false)
-      end
     end
 
     context 'for an existing protected branch' do