diff --git a/lib/api/session.rb b/lib/api/session.rb
index 55ec66a6d674a3a7faeed2df452f7459bf0b30e7..d09400b81f5f21b92d93fedb59501a4fef360af9 100644
--- a/lib/api/session.rb
+++ b/lib/api/session.rb
@@ -1,15 +1,14 @@
 module API
-  # Users API
   class Session < Grape::API
-    # Login to get token
-    #
-    # Parameters:
-    #   login (*required) - user login
-    #   email (*required) - user email
-    #   password (required) - user password
-    #
-    # Example Request:
-    #  POST /session
+    desc 'Login to get token' do
+      success Entities::UserLogin
+    end
+    params do
+      optional :login, type: String, desc: 'The username'
+      optional :email, type: String, desc: 'The email of the user'
+      requires :password, type: String, desc: 'The password of the user'
+      at_least_one_of :login, :email
+    end
     post "/session" do
       user = Gitlab::Auth.find_with_user_password(params[:email] || params[:login], params[:password])
 
diff --git a/spec/requests/api/session_spec.rb b/spec/requests/api/session_spec.rb
index acad1365ace3539167bcb1e8f5907a7bb912d314..e3f22b4c5788df516d33b1786fda2d9f5352ac19 100644
--- a/spec/requests/api/session_spec.rb
+++ b/spec/requests/api/session_spec.rb
@@ -67,22 +67,24 @@ describe API::API, api: true  do
     end
 
     context "when empty password" do
-      it "returns authentication error" do
+      it "returns authentication error with email" do
         post api("/session"), email: user.email
-        expect(response).to have_http_status(401)
 
-        expect(json_response['email']).to be_nil
-        expect(json_response['private_token']).to be_nil
+        expect(response).to have_http_status(400)
+      end
+
+      it "returns authentication error with username" do
+        post api("/session"), email: user.username
+
+        expect(response).to have_http_status(400)
       end
     end
 
     context "when empty name" do
       it "returns authentication error" do
         post api("/session"), password: user.password
-        expect(response).to have_http_status(401)
 
-        expect(json_response['email']).to be_nil
-        expect(json_response['private_token']).to be_nil
+        expect(response).to have_http_status(400)
       end
     end
   end