refactor API and improve docs

lib/api.rb

-require 'api/entities'
-require 'api/helpers'
+Dir["#{Rails.root}/lib/api/*.rb"].each {|file| require file}
 
 module Gitlab
   class API < Grape::API
     format :json
     helpers APIHelpers
 
-    # Users API
-    resource :users do
-      before { authenticate! }
-
-      # GET /users
-      get do
-        @users = User.all
-        present @users, :with => Entities::User
-      end
-
-      # GET /users/:id
-      get ":id" do
-        @user = User.find(params[:id])
-        present @user, :with => Entities::User
-      end
-    end
-
-    # GET /user
-    get "/user" do
-      authenticate!
-      present @current_user, :with => Entities::User
-    end
-
-    # Projects API
-    resource :projects do
-      before { authenticate! }
-
-      # GET /projects
-      get do
-        @projects = current_user.projects
-        present @projects, :with => Entities::Project
-      end
-
-      # GET /projects/:id
-      get ":id" do
-        @project = current_user.projects.find_by_code(params[:id])
-        present @project, :with => Entities::Project
-      end
-
-      # GET /projects/:id/repository/branches
-      get ":id/repository/branches" do
-        @project = current_user.projects.find_by_code(params[:id])
-        present @project.repo.heads.sort_by(&:name), :with => Entities::ProjectRepositoryBranches
-      end
-
-      # GET /projects/:id/repository/tags
-      get ":id/repository/tags" do
-        @project = current_user.projects.find_by_code(params[:id])
-        present @project.repo.tags.sort_by(&:name).reverse, :with => Entities::ProjectRepositoryTags
-      end
-    end
+    mount Users
+    mount Projects
   end
 end

lib/api/projects.rb

+module Gitlab
+  # Projects API
+  class Projects < Grape::API
+    before { authenticate! }
+
+    resource :projects do
+      # Get a projects list for authenticated user
+      #
+      # Example Request:
+      #   GET /projects
+      get do
+        @projects = current_user.projects
+        present @projects, :with => Entities::Project
+      end
+
+      # Get a single project
+      #
+      # Parameters:
+      #   id (required) - The code of a project
+      # Example Request:
+      #   GET /projects/:id
+      get ":id" do
+        @project = current_user.projects.find_by_code(params[:id])
+        present @project, :with => Entities::Project
+      end
+
+      # Get a project repository branches
+      #
+      # Parameters:
+      #   id (required) - The code of a project
+      # Example Request:
+      #   GET /projects/:id/repository/branches
+      get ":id/repository/branches" do
+        @project = current_user.projects.find_by_code(params[:id])
+        present @project.repo.heads.sort_by(&:name), :with => Entities::ProjectRepositoryBranches
+      end
+
+      # Get a project repository tags
+      #
+      # Parameters:
+      #   id (required) - The code of a project
+      # Example Request:
+      #   GET /projects/:id/repository/tags
+      get ":id/repository/tags" do
+        @project = current_user.projects.find_by_code(params[:id])
+        present @project.repo.tags.sort_by(&:name).reverse, :with => Entities::ProjectRepositoryTags
+      end
+    end
+  end
+end

lib/api/users.rb

+module Gitlab
+  # Users API
+  class Users < Grape::API
+    before { authenticate! }
+
+    resource :users do
+      # Get a users list
+      #
+      # Example Request:
+      #  GET /users
+      get do
+        @users = User.all
+        present @users, :with => Entities::User
+      end
+
+      # Get a single user
+      #
+      # Parameters:
+      #   id (required) - The ID of a user
+      # Example Request:
+      #   GET /users/:id
+      get ":id" do
+        @user = User.find(params[:id])
+        present @user, :with => Entities::User
+      end
+    end
+
+    # Get currently authenticated user
+    #
+    # Example Request:
+    #   GET /user
+    get "/user" do
+      present @current_user, :with => Entities::User
+    end
+  end
+end