api docs: Migrate GET /users to OpenAPI.

templates/zerver/api/arguments.json

@@ -1,12 +1,4 @@
 {
-    "get-all-users.md": [
-        {
-            "argument": "client_gravatar",
-            "description": "The `client_gravatar` field is set to `True` if clients can compute their own gravatars. Default is `False`.",
-            "required": false,
-            "example": "`True` or `False`"
-        }
-    ],
     "register-queue.md": [
         {
             "argument": "apply_markdown",

templates/zerver/api/fixtures.json

@@ -9,42 +9,6 @@
         "msg": "Email 'newbie@zulip.com' already in use",
         "result": "error"
     },
-    "get-all-users": {
-        "members": [
-            {
-                "avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
-                "bot_type": null,
-                "email": "AARON@zulip.com",
-                "full_name": "aaron",
-                "is_active": true,
-                "is_admin": false,
-                "is_bot": false,
-                "user_id": 1
-            },
-            {
-                "avatar_url": "https://secure.gravatar.com/avatar/77c3871a68c8d70356156029fd0a4999?d=identicon&version=1",
-                "bot_type": null,
-                "email": "cordelia@zulip.com",
-                "full_name": "Cordelia Lear",
-                "is_active": true,
-                "is_admin": false,
-                "is_bot": false,
-                "user_id": 3
-            },
-            {
-                "avatar_url": "https://secure.gravatar.com/avatar/0cbf08f3a355995fa2ec542246e35123?d=identicon&version=1",
-                "bot_type": null,
-                "email": "newbie@zulip.com",
-                "full_name": "New User",
-                "is_active": true,
-                "is_admin": false,
-                "is_bot": false,
-                "user_id": 24
-            }
-        ],
-        "msg": "",
-        "result": "success"
-    },
     "get-events-from-queue": {
         "events": [
             {

templates/zerver/api/get-all-users.md

@@ -30,7 +30,7 @@ curl {{ api_url }}/v1/users?client_gravatar=true \
 
 <div data-language="python" markdown="1">
 
-{generate_code_example(python)|get-all-users|example}
+{generate_code_example(python)|/users:get|example}
 
 </div>
 
@@ -62,7 +62,7 @@ zulip(config).then((client) => {
 
 **Note**: The following arguments are all URL query parameters.
 
-{generate_api_arguments_table|arguments.json|get-all-users.md}
+{generate_api_arguments_table|zulip.yaml|/users:get}
 
 ## Response
 
@@ -88,4 +88,4 @@ zulip(config).then((client) => {
 
 A typical successful JSON response may look like:
 
-{generate_code_example|get-all-users|fixture}
+{generate_code_example|/users:get|fixture(200)}

zerver/lib/api_test_helpers.py

@@ -130,27 +130,14 @@ def get_members(client):
     result = client.get_members()
     # {code_example|end}
 
-    fixture = FIXTURES['get-all-users']
+    validate_against_openapi_schema(result, '/users', 'get', '200')
-    test_against_fixture(result, fixture, check_if_equal=['msg', 'result'],
+
-                         check_if_exists=['members'])
     members = [m for m in result['members'] if m['email'] == 'newbie@zulip.com']
     assert len(members) == 1
     newbie = members[0]
     assert not newbie['is_admin']
     assert newbie['full_name'] == 'New User'
 
-    member_fixture = fixture['members'][0]
-
-    # Get Aaron from all the results we got from the API
-    for member in result['members']:
-        if member['email'] == 'AARON@zulip.com':
-            member_result = member
-
-    assert member_result
-
-    test_against_fixture(member_result, member_fixture,
-                         check_if_exists=member_fixture.keys())
-
     # {code_example|start}
     # You may pass the `client_gravatar` query parameter as follows:
     result = client.call_endpoint(
@@ -159,8 +146,7 @@ def get_members(client):
     )
     # {code_example|end}
 
-    test_against_fixture(result, fixture, check_if_equal=['msg', 'result'],
+    validate_against_openapi_schema(result, '/users', 'get', '200')
-                         check_if_exists=['members'])
     assert result['members'][0]['avatar_url'] is None
 
 def get_profile(client):
@@ -501,7 +487,7 @@ TEST_FUNCTIONS = {
     'get-profile': get_profile,
     'add-subscriptions': add_subscriptions,
     'remove-subscriptions': remove_subscriptions,
-    'get-all-users': get_members,
+    '/users:get': get_members,
     'register-queue': register_queue,
     'delete-queue': deregister_queue,
     'upload-file': upload_file,

zerver/openapi/zulip.yaml

@@ -261,6 +261,71 @@ paths:
                         "rendered": "<p><strong>foo</strong></p>",
                         "result": "success"
                     }
+  /users:
+    get:
+      description: Retrieve all users in a realm.
+      parameters:
+      - name: client_gravatar
+        in: query
+        description: The `client_gravatar` field is set to `true` if clients
+          can compute their own gravatars.
+        schema:
+           type: boolean
+           default : false
+        example: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    members:
+                      type: array
+                      description: A list of `member` objects, each containing
+                        details of a user in the realm (like their email, name,
+                        avatar, user type...).
+                - example:
+                    {
+                        "members": [
+                            {
+                                "avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
+                                "bot_type": null,
+                                "email": "AARON@zulip.com",
+                                "full_name": "aaron",
+                                "is_active": true,
+                                "is_admin": false,
+                                "is_bot": false,
+                                "user_id": 1
+                            },
+                            {
+                                "avatar_url": "https://secure.gravatar.com/avatar/77c3871a68c8d70356156029fd0a4999?d=identicon&version=1",
+                                "bot_type": null,
+                                "email": "cordelia@zulip.com",
+                                "full_name": "Cordelia Lear",
+                                "is_active": true,
+                                "is_admin": false,
+                                "is_bot": false,
+                                "user_id": 3
+                            },
+                            {
+                                "avatar_url": "https://secure.gravatar.com/avatar/0cbf08f3a355995fa2ec542246e35123?d=identicon&version=1",
+                                "bot_type": null,
+                                "email": "newbie@zulip.com",
+                                "full_name": "New User",
+                                "is_active": true,
+                                "is_admin": false,
+                                "is_bot": false,
+                                "user_id": 24
+                            }
+                        ],
+                        "msg": "",
+                        "result": "success"
+                    }
   /users/me/{stream_id}/topics:
     get:
       description: Get all the topics in a specific stream.