Grapify boards APIgrapify-boards-api

1 files changed, 37 insertions, 29 deletions

diff --git a/lib/api/boards.rb b/lib/api/boards.rb
index 9b71d335128..4bfcaafc6ca 100644
--- a/lib/api/boards.rb
+++ b/lib/api/boards.rb
@@ -3,13 +3,21 @@ 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
+        success Entities::Board
+      end
       get ':id/boards' do
         authorize!(:read_board, user_project)
         present user_project.boards, with: Entities::Board
       end
 
+      params do
+        requires :id, type: String, desc: 'The ID of a board'
+      end
       segment ':id/boards/:board_id' do
         helpers do
           def project_board
@@ -27,29 +35,33 @@ 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'
+          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
+          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
+          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,14 +80,12 @@ 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
+          success Entities::List
+        end
+        params do
+          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])
 
@@ -91,14 +101,12 @@ 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
+          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)