api_docs: Add documentation for remove_user_group.

templates/zerver/api/delete-user-group.md

@@ -0,0 +1,37 @@
+# Delete a user group
+
+Delete a [user group](/help/user-groups).
+
+`DELETE {{ api_url }}/v1/user_groups/{group_id}`
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/user_groups/{group_id}:delete|example}
+
+{tab|curl}
+
+``` curl
+curl -X DELETE {{ api_url }}/v1/user_groups/42 \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+```
+
+{end_tabs}
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/user_groups/{group_id}:delete}
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/user_groups/{group_id}:delete|fixture(200)}
+
+An example JSON error response for an invalid user group id:
+
+{generate_code_example|/user_groups/{group_id}:delete|fixture(400)}

templates/zerver/help/include/rest-endpoints.md

@@ -37,6 +37,7 @@
 * [Update notification settings](/api/update-notification-settings)
 * [Create a user group](/api/create-user-group)
 * [Update a user group](/api/update-user-group)
+* [Delete a user group](/api/delete-user-group)
 
 #### Server & organizations
 

zerver/lib/api_test_helpers.py

@@ -906,8 +906,11 @@ def update_user_group(client, group_id):
 
 def remove_user_group(client, group_id):
     # type: (Client, int) -> None
+    # {code_example|start}
     result = client.remove_user_group(group_id)
+    # {code_example|end}
 
+    validate_against_openapi_schema(result, '/user_groups/{group_id}', 'delete', '200')
     assert result['result'] == 'success'
 
 def update_user_group_members(client, group_id):

zerver/openapi/zulip.yaml

@@ -2299,6 +2299,46 @@ paths:
                         "msg": "Invalid user group",
                         "result": "error"
                     }
+    delete:
+      description: Delete the user group.
+      parameters:
+      - name: group_id
+        in: path
+        description: The ID of the group.
+        schema:
+          type: integer
+        example: 42
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - example:
+                      {
+                          "result": "success",
+                          "msg": "",
+                      }
+
+        '400':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonError'
+                - example:
+                    {
+                        "code": "BAD_REQUEST",
+                        "msg": "Invalid user group",
+                        "result": "error"
+                    }
+
   /user_groups:
     get:
       description: Get all user groups of the realm.