Refine and document controllers

app/controllers/passwords_controller.rb

@@ -9,7 +9,7 @@ class PasswordsController < ApplicationController
       PasswordsMailer.reset(user).deliver_later
     end
 
-    render json: {}, status: :ok
+    render json: {}, status: :created
   end
 
   def update
@@ -25,6 +25,6 @@ class PasswordsController < ApplicationController
   def set_user_by_token
     @user = User.find_by_password_reset_token!(params[:token])
   rescue ActiveSupport::MessageVerifier::InvalidSignature
-    redirect_to new_password_path, alert: 'Password reset link is invalid or has expired.'
+    render json: { errors: ['Password reset link is invalid or has expired.'] }, status: :unprocessable_entity
   end
 end

spec/requests/passwords_spec.rb

@@ -0,0 +1,40 @@
+require 'swagger_helper'
+
+RSpec.describe 'passwords', type: :request do
+  path '/passwords' do
+    post('send a password (re)set email') do
+      tags 'Passwords'
+      consumes 'application/json'
+      produces 'application/json'
+      parameter name: :body, in: :body, schema: {
+        type: :object,
+        required: [:email_address],
+        properties: {
+          email_address: { type: :string, format: :email }
+        }
+      }
+
+      response_empty_201
+    end
+  end
+
+  path '/passwords/{token}' do
+    parameter name: 'token', in: :path, type: :string, description: 'token'
+    put('update password') do
+      tags 'Passwords'
+      consumes 'application/json'
+      produces 'application/json'
+      parameter name: :body, in: :body, schema: {
+        type: :object,
+        required: %i[password password_confirmation],
+        properties: {
+          password: { type: :string },
+          password_confirmation: { type: :string }
+        }
+      }
+
+      response_empty_200
+      response_422
+    end
+  end
+end

spec/requests/sessions_spec.rb

@@ -0,0 +1,29 @@
+require 'swagger_helper'
+
+RSpec.describe 'sessions', type: :request do
+  path '/session' do
+    delete('delete session') do
+      tags 'Sessions'
+      produces 'application/json'
+      response_empty_200
+    end
+
+    post('create session') do
+      tags 'Sessions'
+      consumes 'application/json'
+      produces 'application/json'
+      parameter name: :body, in: :body, schema: {
+        type: :object,
+        required: %i[email_address password],
+        properties: {
+          email_address: { type: :string, format: :email },
+          password: { type: :string }
+        }
+      }
+
+      response_empty_201
+      response_401
+      response_429
+    end
+  end
+end

spec/swagger_response_helper.rb

@@ -9,6 +9,22 @@ module SwaggerResponseHelper
     end
   end
 
+  def response_429
+    response(429, 'Rate limit exceeded') do
+      produces 'application/json'
+      error_schema
+      xit
+    end
+  end
+
+  def response_401
+    response(401, 'Unauthorized') do
+      produces 'application/json'
+      error_schema
+      xit
+    end
+  end
+
   def response_empty_200
     response(200, 'Success') do
       produces 'application/json'