From 1b2f67f1bfc835ef8173a55f10442d12e21b222d Mon Sep 17 00:00:00 2001
From: sameerchoubey <sameer.choubey98@gmail.com>
Date: Tue, 25 Jun 2019 01:57:06 +0530
Subject: [PATCH] api_docs: Add documentation for create_user_group.

---
 templates/zerver/api/create-user-group.md     | 40 ++++++++++++++
 .../zerver/help/include/rest-endpoints.md     |  1 +
 zerver/lib/api_test_helpers.py                |  9 ++-
 zerver/openapi/zulip.yaml                     | 55 +++++++++++++++++++
 4 files changed, 102 insertions(+), 3 deletions(-)
 create mode 100644 templates/zerver/api/create-user-group.md

diff --git a/templates/zerver/api/create-user-group.md b/templates/zerver/api/create-user-group.md
new file mode 100644
index 0000000000..a4c08d6760
--- /dev/null
+++ b/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)}
diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md
index 16c2890560..2eae9cdb47 100644
--- a/templates/zerver/help/include/rest-endpoints.md
+++ b/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
 
diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py
index edae23ac08..431a56109c 100644
--- a/zerver/lib/api_test_helpers.py
+++ b/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'
 
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 058796c66a..ed28e24ca8 100644
--- a/zerver/openapi/zulip.yaml
+++ b/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.