Merge branch 'grapify-session-api' into 'master'

Grapify the session API

## What are the relevant issue numbers?

Related to #22928

See merge request !7381

lib/api/session.rb

 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])

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