DEV: Document the user suspend api endpoint (#12179)

Wrote an api docs rspec test for documenting the user suspend api
endpoint.

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"
+  ]
+}
+

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"
+  ]
+}

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