api: Add GET /user_groups documentation.

This documents our GET endpoint for interacting with Zulip's user
groups feature.

Fixes #10298.

templates/zerver/api/get-user-groups.md

@@ -0,0 +1,54 @@
+# Get user groups
+
+Fetches all of the user groups in the organization.
+
+`GET {{ api_url }}/v1/user_groups`
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/user_groups \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/user_groups:get|example}
+
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/user_groups:get}
+
+## Response
+
+#### Return values
+
+* `user_groups`: A list of dictionaries, where each dictionary contains information
+  about a user group.
+    * `description`: The human-readable description of the user group.
+    * `id`: The user group's integer id.
+    * `members`: The integer User IDs of the user group members.
+    * `name`: User group name.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/user_groups:get|fixture(200)}

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

@@ -31,6 +31,7 @@
 * [Create a user](/api/create-user)
 * [Set "typing" status](/api/typing)
 * [Get user presence](/api/get-presence)
+* [Get all user groups](/api/get-user-groups)
 
 #### Server & organizations
 

zerver/lib/api_test_helpers.py

@@ -234,6 +234,18 @@ def get_streams(client):
     validate_against_openapi_schema(result, '/streams', 'get', '200')
     assert len(result['streams']) == 4
 
+def get_user_groups(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Get all user groups of the realm
+    result = client.get_user_groups()
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/user_groups', 'get', '200')
+    user_groups = [u for u in result['user_groups'] if u['name'] == "hamletcharacters"]
+    assert user_groups[0]['description'] == 'Characters of Hamlet'
+
 def test_user_not_authorized_error(nonadmin_client):
     # type: (Client) -> None
     result = nonadmin_client.get_streams(include_all_active=True)
@@ -793,6 +805,7 @@ TEST_FUNCTIONS = {
     '/user_uploads:post': upload_file,
     '/users/me/{stream_id}/topics:get': get_stream_topics,
     '/typing:post': set_typing_status,
+    '/user_groups:get': get_user_groups,
 }
 
 # SETUP METHODS FOLLOW
@@ -871,6 +884,7 @@ def test_users(client):
     upload_file(client)
     set_typing_status(client)
     get_user_presence(client)
+    get_user_groups(client)
 
 def test_streams(client, nonadmin_client):
     # type: (Client, Client) -> None

zerver/openapi/zulip.yaml

@@ -1895,6 +1895,46 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/JsonSuccess'
+  /user_groups:
+    get:
+      description: Get all user groups of the realm.
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    user_groups:
+                      type: array
+                      items:
+                        type: object
+                      description: A list of `user_group` objects, which contain a
+                        `description`, a `name`, their `id` and the list of members
+                        of the user group.
+                - example:
+                    {
+                        "msg": "",
+                        "result": "success",
+                        "user_groups": [
+                            {
+                                "description": "Characters of Hamlet",
+                                "id": 1,
+                                "name": "hamletcharacters",
+                                "members": [3, 4]
+                            },
+                            {
+                                "description": "Other users",
+                                "id": 2,
+                                "name": "other users",
+                                "members": [1, 2]
+                            }
+                        ]
+                    }
 components:
   #######################
   # Security definitions