docs: Explain link sharing in /api/upload-file.

Rewrittten by tabbott to clearly explain the security model, and add a
code example.

templates/zerver/api/upload-file.md

@@ -4,6 +4,15 @@ Upload a single file and get the corresponding URI.
 
 `POST {{ api_url }}/v1/user_uploads`
 
+Initially, only you will be able to access the link.  To share the
+uploaded file, you'll need to [send a message][send-message]
+containing the resulting link.  Users who can already access the link
+can reshare it with other users by sending additional Zulip messages
+containing the link.
+
+[uploaded-files]: /help/manage-your-uploaded-files
+[send-message]: /api/send-message
+
 ## Usage examples
 
 {start_tabs}

zerver/openapi/python_examples.py

@@ -882,6 +882,13 @@ def upload_file(client):
             method='POST',
             files=[fp]
         )
+
+    client.send_message({
+        "type": "stream",
+        "to": "Denmark",
+        "topic": "Castle",
+        "content": "Check out [this picture](%s) of my castle!" % (result['uri'],)
+    })
     # {code_example|end}
 
     validate_against_openapi_schema(result, '/user_uploads', 'post', '200')