From 0b2b4bc245e3a276444a5890b4ba652c5db42bc3 Mon Sep 17 00:00:00 2001
From: Blake Erickson <o.blakeerickson@gmail.com>
Date: Tue, 23 Feb 2021 05:58:22 -0700
Subject: [PATCH] DEV: Document the user suspend api endpoint (#12179)

Wrote an api docs rspec test for documenting the user suspend api
endpoint.
---
 .../schemas/json/user_suspend_request.json    | 25 +++++++++++++++
 .../schemas/json/user_suspend_response.json   | 32 +++++++++++++++++++
 spec/requests/api/users_spec.rb               | 29 +++++++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 spec/requests/api/schemas/json/user_suspend_request.json
 create mode 100644 spec/requests/api/schemas/json/user_suspend_response.json

diff --git a/spec/requests/api/schemas/json/user_suspend_request.json b/spec/requests/api/schemas/json/user_suspend_request.json
new file mode 100644
index 00000000000..7ccb864e854
--- /dev/null
+++ b/spec/requests/api/schemas/json/user_suspend_request.json
@@ -0,0 +1,25 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "suspend_until": {
+      "type": "string",
+      "example": "2121-02-22"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string",
+      "description": "Will send an email with this message when present"
+    },
+    "post_action": {
+      "type": "string",
+      "example": "delete"
+    }
+  },
+  "required": [
+    "suspend_until",
+    "reason"
+  ]
+}
+
diff --git a/spec/requests/api/schemas/json/user_suspend_response.json b/spec/requests/api/schemas/json/user_suspend_response.json
new file mode 100644
index 00000000000..d6d091283be
--- /dev/null
+++ b/spec/requests/api/schemas/json/user_suspend_response.json
@@ -0,0 +1,32 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "suspension": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "suspend_reason": {
+          "type": "string"
+        },
+        "full_suspend_reason": {
+          "type": "string"
+        },
+        "suspended_till": {
+          "type": "string"
+        },
+        "suspended_at": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "suspend_reason",
+        "full_suspend_reason",
+        "suspended_till",
+        "suspended_at"
+      ]
+    }
+  },
+  "required": [
+    "suspension"
+  ]
+}
diff --git a/spec/requests/api/users_spec.rb b/spec/requests/api/users_spec.rb
index c90060446c8..13a7f1842f5 100644
--- a/spec/requests/api/users_spec.rb
+++ b/spec/requests/api/users_spec.rb
@@ -308,6 +308,35 @@ describe 'users' do
 
   end
 
+  path '/admin/users/{id}/suspend.json' do
+    put 'Suspend a user' do
+      tags 'Users', 'Admin'
+      consumes 'application/json'
+      expected_request_schema = load_spec_schema('user_suspend_request')
+
+      parameter name: :id, in: :path, type: :integer, required: true
+      parameter name: :params, in: :body, schema: expected_request_schema
+
+      produces 'application/json'
+      response '200', 'response' do
+
+        let(:id) { Fabricate(:user).id }
+        let(:params) { {
+          'suspend_until' => '2121-02-22',
+          'reason' => 'inactivity'
+        } }
+
+        expected_response_schema = load_spec_schema('user_suspend_response')
+        schema(expected_response_schema)
+
+        it_behaves_like "a JSON endpoint", 200 do
+          let(:expected_response_schema) { expected_response_schema }
+          let(:expected_request_schema) { expected_request_schema }
+        end
+      end
+    end
+  end
+
   path '/admin/users/{id}/log_out.json' do
 
     post 'Log a user out' do