api: Document GET ../users/{user_id} endpoint.

This adds get_single_user to python_examples.py in zerver/openapi.
This also adds get-single-user.md to templates/zerver/api and adds
get-single-user to rest-endpoints.md (templates/zerver/help/include).

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

@@ -1,9 +1,12 @@
 # Get all users
 
-Retrieve all users in a realm.
+Retrieve details on all users in the organization.  Optionally
+includes values of [custom profile field](/help/add-custom-profile-fields).
 
 `GET {{ api_url }}/v1/users`
 
+You can also [fetch details on a single user](/api/get-user).
+
 ## Usage examples
 
 {start_tabs}

templates/zerver/api/get-user.md

@@ -0,0 +1,58 @@
+# Get a user
+
+Fetch details for a single user in the organization.
+
+`GET {{ api_url }}/v1/users/{user_id}`
+
+You can also fetch details on [all users in the organization](/api/get-all-users).
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/users/{user_id}:get|example}
+
+{tab|curl}
+
+{generate_code_example(curl, include=[""])|/users/{user_id}:get|example}
+
+You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
+
+{generate_code_example(curl)|/users/{user_id}:get|example}
+
+{end_tabs}
+
+## Arguments
+
+**Note**: The following arguments are all URL query parameters.
+
+{generate_api_arguments_table|zulip.yaml|/users/{user_id}:get}
+
+## Response
+
+#### Return values
+
+* `members`: A list with a single dictionary that contains information
+  about a particular user or bot.
+    * `email`: The email address of the user or bot.
+    * `is_bot`: A boolean specifying whether the user is a bot or not.
+    * `avatar_url`: URL to the user's gravatar. `None` if the `client_gravatar`
+      query paramater was set to `True`.
+    * `full_name`: Full name of the user or bot.
+    * `is_admin`: A boolean specifying whether the user is an admin or not.
+    * `bot_type`: `None` if the user isn't a bot. `1` for a `Generic` bot.
+      `2` for an `Incoming webhook` bot. `3` for an `Outgoing webhook` bot.
+      `4` for an `Embedded` bot.
+    * `user_id`: The ID of the user.
+    * `bot_owner`: If the user is a bot (i.e. `is_bot` is `True`), `bot_owner`
+      is the email address of the user who created the bot.
+    * `is_active`: A boolean specifying whether the user is active or not.
+    * `is_guest`: A boolean specifying whether the user is a guest user or not.
+    * `timezone`: The time zone of the user.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/users/{user_id}:get|fixture(200)}

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

@@ -29,6 +29,7 @@
 #### Users
 
 * [Get all users](/api/get-all-users)
+* [Get a user](/api/get-user)
 * [Get profile](/api/get-profile)
 * [Create a user](/api/create-user)
 * [Set "typing" status](/api/typing)

zerver/openapi/python_examples.py

@@ -216,6 +216,32 @@ def get_members(client):
         else:
             assert member.get('profile_data', None) is not None
 
+@openapi_test_function("/users/{user_id}:get")
+def get_single_user(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Fetch details on a user given a user ID
+    user_id = 8
+    url = 'users/' + str(user_id)
+    result = client.call_endpoint(
+        url=url,
+        method='GET'
+    )
+    # {code_example|end}
+    validate_against_openapi_schema(result, '/users/{user_id}', 'get', '200')
+
+    # {code_example|start}
+    # If you'd like data on custom profile fields, you can request them as follows:
+    result = client.call_endpoint(
+        url=url,
+        method='GET',
+        request={'include_custom_profile_fields': True}
+    )
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/users/{user_id}', 'get', '200')
+
 @openapi_test_function("/realm/filters:get")
 def get_realm_filters(client):
     # type: (Client) -> None
@@ -1123,6 +1149,7 @@ def test_users(client):
 
     create_user(client)
     get_members(client)
+    get_single_user(client)
     get_profile(client)
     update_notification_settings(client)
     upload_file(client)