DEV: Tidy up create group api endpoint docs (#17586)

Switch to using json schema files for describing the requests and
responses.

spec/requests/api/groups_spec.rb

@@ -15,62 +15,17 @@ describe 'groups' do
       tags 'Groups'
       operationId 'createGroup'
       consumes 'application/json'
-      parameter name: :group, in: :body, schema: {
+      expected_request_schema = load_spec_schema('group_create_request')
-        type: :object,
+      parameter name: :params, in: :body, schema: expected_request_schema
-        properties: {
-          group: {
-            type: :object,
-            properties: {
-              name: { type: :string },
-            }, required: ['name']
-          }
-        }, required: ['group']
-      }
 
       produces 'application/json'
       response '200', 'group created' do
-        schema type: :object, properties: {
+        expected_response_schema = load_spec_schema('group_create_response')
-            basic_group: {
-              type: :object,
-              properties: {
-                id: { type: :integer },
-                automatic: { type: :boolean },
-                name: { type: :string },
-                user_count: { type: :integer },
-                mentionable_level: { type: :integer },
-                messageable_level: { type: :integer },
-                visibility_level: { type: :integer },
-                automatic_membership_email_domains: { type: [:string, :null] },
-                automatic_membership_retroactive: { type: :boolean },
-                primary_group: { type: :boolean },
-                title: { type: [:string, :null] },
-                grant_trust_level: { type: [:string, :null] },
-                incoming_email: { type: [:string, :null] },
-                has_messages: { type: :boolean },
-                flair_url: { type: [:string, :null] },
-                flair_bg_color: { type: [:string, :null] },
-                flair_color: { type: [:string, :null] },
-                bio_raw: { type: [:string, :null] },
-                bio_cooked: { type: [:string, :null] },
-                bio_excerpt: { type: [:string, :null] },
-                public_admission: { type: :boolean },
-                public_exit: { type: :boolean },
-                allow_membership_requests: { type: :boolean },
-                full_name: { type: [:string, :null] },
-                default_notification_level: { type: :integer },
-                membership_request_template: { type: [:string, :null] },
-                membership_visibility_level: { type: :integer },
-                can_see_members: { type: :boolean },
-                publish_read_state: { type: :boolean },
-              },
-              required: ["id"]
-            }
-          }, required: ["basic_group"]
 
-        let(:group) { { name: 'awesome' } }
+        let(:params) { { 'group' => { 'name' => 'awesome' } } }
-        run_test! do |response|
+        it_behaves_like "a JSON endpoint", 200 do
-          data = JSON.parse(response.body)
+          let(:expected_response_schema) { expected_response_schema }
-          expect(data['basic_group']['name']).to eq("awesome")
+          let(:expected_request_schema) { expected_request_schema }
         end
       end
     end

spec/requests/api/schemas/json/group_create_request.json

@@ -0,0 +1,20 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "group": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ]
+    }
+  },
+  "required": [
+    "group"
+  ]
+}

spec/requests/api/schemas/json/group_create_response.json

@@ -0,0 +1,161 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "basic_group": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "automatic": {
+          "type": "boolean"
+        },
+        "name": {
+          "type": "string"
+        },
+        "user_count": {
+          "type": "integer"
+        },
+        "mentionable_level": {
+          "type": "integer"
+        },
+        "messageable_level": {
+          "type": "integer"
+        },
+        "visibility_level": {
+          "type": "integer"
+        },
+        "primary_group": {
+          "type": "boolean"
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "grant_trust_level": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "incoming_email": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "has_messages": {
+          "type": "boolean"
+        },
+        "flair_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "flair_bg_color": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "flair_color": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "bio_raw": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "bio_cooked": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "bio_excerpt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "public_admission": {
+          "type": "boolean"
+        },
+        "public_exit": {
+          "type": "boolean"
+        },
+        "allow_membership_requests": {
+          "type": "boolean"
+        },
+        "full_name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "default_notification_level": {
+          "type": "integer"
+        },
+        "membership_request_template": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "members_visibility_level": {
+          "type": "integer"
+        },
+        "can_see_members": {
+          "type": "boolean"
+        },
+        "can_admin_group": {
+          "type": "boolean"
+        },
+        "publish_read_state": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "id",
+        "automatic",
+        "name",
+        "user_count",
+        "mentionable_level",
+        "messageable_level",
+        "visibility_level",
+        "primary_group",
+        "title",
+        "grant_trust_level",
+        "incoming_email",
+        "has_messages",
+        "flair_url",
+        "flair_bg_color",
+        "flair_color",
+        "bio_raw",
+        "bio_cooked",
+        "bio_excerpt",
+        "public_admission",
+        "public_exit",
+        "allow_membership_requests",
+        "full_name",
+        "default_notification_level",
+        "membership_request_template",
+        "members_visibility_level",
+        "can_see_members",
+        "can_admin_group",
+        "publish_read_state"
+      ]
+    }
+  },
+  "required": [
+    "basic_group"
+  ]
+}