Grapify boards API

lib/api/boards.rb

@@ -3,19 +3,28 @@ module API
   class Boards < Grape::API
     before { authenticate! }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
-      # Get the project board
+      desc 'Get all project boards' do
+        detail 'This feature was introduced in 8.13'
+        success Entities::Board
+      end
       get ':id/boards' do
         authorize!(:read_board, user_project)
         present user_project.boards, with: Entities::Board
       end
 
+      params do
+        requires :board_id, type: Integer, desc: 'The ID of a board'
+      end
       segment ':id/boards/:board_id' do
         helpers do
           def project_board
             board = user_project.boards.first
 
-            if params[:board_id].to_i == board.id
+            if params[:board_id] == board.id
               board
             else
               not_found!('Board')
@@ -27,29 +36,35 @@ module API
           end
         end
 
-        # Get the lists of a project board
-        # Does not include `backlog` and `done` lists
+        desc 'Get the lists of a project board' do
+          detail 'Does not include `backlog` and `done` lists. This feature was introduced in 8.13'
+          success Entities::List
+        end
         get '/lists' do
           authorize!(:read_board, user_project)
           present board_lists, with: Entities::List
         end
 
-        # Get a list of a project board
+        desc 'Get a list of a project board' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :list_id, type: Integer, desc: 'The ID of a list'
+        end
         get '/lists/:list_id' do
           authorize!(:read_board, user_project)
           present board_lists.find(params[:list_id]), with: Entities::List
         end
 
-        # Create a new board list
-        #
-        # Parameters:
-        #   id (required)           - The ID of a project
-        #   label_id (required)     - The ID of an existing label
-        # Example Request:
-        #   POST /projects/:id/boards/:board_id/lists
+        desc 'Create a new board list' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :label_id, type: Integer, desc: 'The ID of an existing label'
+        end
         post '/lists' do
-          required_attributes! [:label_id]
-
           unless user_project.labels.exists?(params[:label_id])
             render_api_error!({ error: "Label not found!" }, 400)
           end
@@ -68,21 +83,21 @@ module API
           end
         end
 
-        # Moves a board list to a new position
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   board_id (required) - The ID of a board
-        #   position (required) - The position of the list
-        # Example Request:
-        #   PUT /projects/:id/boards/:board_id/lists/:list_id
+        desc 'Moves a board list to a new position' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :list_id,  type: Integer, desc: 'The ID of a list'
+          requires :position, type: Integer, desc: 'The position of the list'
+        end
         put '/lists/:list_id' do
           list = project_board.lists.movable.find(params[:list_id])
 
           authorize!(:admin_list, user_project)
 
           service = ::Boards::Lists::MoveService.new(user_project, current_user,
-              { position: params[:position].to_i })
+              { position: params[:position] })
 
           if service.execute(list)
             present list, with: Entities::List
@@ -91,14 +106,13 @@ module API
           end
         end
 
-        # Delete a board list
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   board_id (required) - The ID of a board
-        #   list_id (required) - The ID of a board list
-        # Example Request:
-        #   DELETE /projects/:id/boards/:board_id/lists/:list_id
+        desc 'Delete a board list' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :list_id, type: Integer, desc: 'The ID of a board list'
+        end
         delete "/lists/:list_id" do
           authorize!(:admin_list, user_project)