api docs: Document POST /user_groups/{group_id}/members endpoint.

templates/zerver/api/update-user-group-members.md

@@ -0,0 +1,28 @@
+# Update user group members
+
+{generate_api_description(/user_groups/{user_group_id}/members:post)}
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/user_groups/{user_group_id}/members:post|example}
+
+{tab|curl}
+
+{generate_code_example(curl, exclude=["delete"])|/user_groups/{user_group_id}/members:post|example}
+
+{end_tabs}
+
+## Parameters
+
+{generate_api_arguments_table|zulip.yaml|/user_groups/{user_group_id}/members:post}
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/user_groups/{user_group_id}/members:post|fixture(200)}

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

@@ -47,6 +47,7 @@
 * [Create a user group](/api/create-user-group)
 * [Update a user group](/api/update-user-group)
 * [Delete a user group](/api/remove-user-group)
+* [Update user group members](/api/update-user-group-members)
 
 #### Server & organizations
 

zerver/openapi/python_examples.py

@@ -1127,7 +1127,7 @@ def remove_user_group(client: Client, user_group_id: int) -> None:
 @openapi_test_function("/user_groups/{user_group_id}/members:post")
 def update_user_group_members(client: Client, user_group_id: int) -> None:
     ensure_users([8, 10, 11], ['cordelia', 'hamlet', 'iago'])
-
+    # {code_example|start}
     request = {
         'group_id': user_group_id,
         'delete': [8, 10],
@@ -1135,8 +1135,8 @@ def update_user_group_members(client: Client, user_group_id: int) -> None:
     }
 
     result = client.update_user_group_members(request)
-
+    # {code_example|end}
-    assert result['result'] == 'success'
+    validate_against_openapi_schema(result, '/user_groups/{group_id}/members', 'post', '200')
 
 def test_invalid_api_key(client_with_invalid_key: Client) -> None:
     result = client_with_invalid_key.list_subscriptions()

zerver/openapi/zulip.yaml

@@ -8100,6 +8100,44 @@ paths:
                         "code": "BAD_REQUEST",
                         "msg": "Invalid user ID: 500",
                       }
+  /user_groups/{user_group_id}/members:
+    post:
+      operationId: update_user_group_members
+      tags: ["users"]
+      description: |
+        Update the members of a [user group](/help/user-groups).
+
+        `POST {{ api_url }}/v1/user_groups/{user_group_id}/members`
+      parameters:
+        - $ref: "#/components/parameters/UserGroupId"
+          example: 1
+        - name: delete
+          in: query
+          description: |
+            The list of user ids to be removed from the user group.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: integer
+              example: [10]
+          required: false
+        - name: add
+          in: query
+          description: |
+            The list of user ids to be added to the user group.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: integer
+              example: [12, 13]
+          required: false
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
   /user_groups/{user_group_id}:
     patch:
       operationId: update_user_group

zerver/tests/test_openapi.py

@@ -292,7 +292,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         '/calls/zoom/create',
 
         #### Documented endpoints not properly detected by tooling.
-        '/user_groups/{user_group_id}/members',
         # Regex with an unnamed capturing group.
         '/users/(?!me/)(?P<email>[^/]*)/presence',
     }