api_docs: Add documentation for create_user_group.

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

@@ -0,0 +1,40 @@
+# Create User Group
+
+Create a new [user group](/help/user-groups).
+
+`POST {{ api_url }}/v1/user_groups/create`
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/user_groups/create:post|example}
+
+{tab|curl}
+
+``` curl
+curl -X POST {{ api_url }}/v1/user_groups/create \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d 'name="marketing"' \
+    -d 'description="The marketing team"' \
+    -d 'members=[1,2,3,4]'
+```
+
+{end_tabs}
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/user_groups/create:post}
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/user_groups/create:post|fixture(200)}
+
+An example JSON error response for when the one of the users does not exist:
+
+{generate_code_example|/user_groups/create:post|fixture(400)}

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

@@ -35,6 +35,7 @@
 * [Get user presence](/api/get-presence)
 * [Get all user groups](/api/get-user-groups)
 * [Update notification settings](/api/update-notification-settings)
+* [Create a user group](/api/create-user-group)
 
 #### Server & organizations
 

zerver/lib/api_test_helpers.py

@@ -878,13 +878,16 @@ def remove_alert_words(client):
 
 def create_user_group(client):
     # type: (Client) -> None
+    # {code_example|start}
     request = {
-        'name': 'Manchester United',
-        'description': "Ole's at the Wheel.",
-        'members': [1, 2, 3, 4]
+        'name': 'marketing',
+        'description': 'The marketing team.',
+        'members': [1, 2, 3, 4],
     }
 
     result = client.create_user_group(request)
+    # {code_example|end}
+    validate_against_openapi_schema(result, '/user_groups/create', 'post', '200')
 
     assert result['result'] == 'success'
 

zerver/openapi/zulip.yaml

@@ -2189,6 +2189,61 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/JsonSuccess'
+
+  /user_groups/create:
+    post:
+      description: Create a user group.
+      parameters:
+      - name: name
+        in: query
+        description: The name of the user group.
+        schema:
+          type: string
+        example: marketing
+        required: true
+      - name: description
+        in: query
+        description: The description of the user group.
+        schema:
+          type: string
+        example: The marketing team.
+        required: true
+      - name: members
+        in: query
+        description: An array containing the user IDs of the initial members for the new user group.
+        schema:
+          type: array
+        example: [1, 2, 3, 4]
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - example:
+                      {
+                          "msg": "",
+                          "result": "success"
+                      }
+        '400':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonError'
+                - example:
+                    {
+                      "result": "error",
+                      "code": "BAD_REQUEST",
+                      "msg": "Invalid user ID: 500"
+                    }
+
   /user_groups:
     get:
       description: Get all user groups of the realm.