openapi: Document GET /attachments endpoint.

templates/zerver/api/get-attachments.md

@@ -0,0 +1,32 @@
+# Get attachments
+
+{generate_api_description(/attachments:get)}
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/attachments:get|example}
+
+{tab|curl}
+
+{generate_code_example(curl)|/attachments:get|example}
+
+{end_tabs}
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/attachments:get}
+
+## Response
+
+#### Return values
+
+{generate_return_values_table|zulip.yaml|/attachments:get}
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/attachments:get|fixture(200)}

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

@@ -45,6 +45,7 @@
 * [Create a user group](/api/create-user-group)
 * [Update a user group](/api/update-user-group)
 * [Delete a user group](/api/delete-user-group)
+* [Get attachments](/api/get-attachments)
 
 #### Server & organizations
 

zerver/openapi/python_examples.py

@@ -596,6 +596,15 @@ def get_raw_message(client: Client, message_id: int) -> None:
     validate_against_openapi_schema(result, '/messages/{message_id}', 'get',
                                     '200')
 
+@openapi_test_function("/attachments:get")
+def get_attachments(client: Client) -> None:
+    # {code_example|start}
+    # Get your attachments.
+
+    result = client.get_attachments()
+    # {code_example|end}
+    validate_against_openapi_schema(result, '/attachments', 'get', '200')
+
 @openapi_test_function("/messages:post")
 def send_message(client: Client) -> int:
 
@@ -1132,6 +1141,7 @@ def test_users(client: Client) -> None:
     get_profile(client)
     update_notification_settings(client)
     upload_file(client)
+    get_attachments(client)
     set_typing_status(client)
     update_presence(client)
     get_user_presence(client)

zerver/openapi/zulip.yaml

@@ -341,6 +341,94 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/JsonSuccess'
+  /attachments:
+    get:
+      operationId: get_attachments
+      tags: ["users"]
+      description: |
+        Fetch metadata on files uploaded by the requesting user.
+
+        `GET {{ api_url }}/v1/attachments`
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    attachments:
+                      type: array
+                      description: |
+                        A list of `attachment` objects, each containing
+                        details about a file uploaded by the user.
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: integer
+                            description: |
+                              The unique ID for the attachment.
+                          name:
+                            type: string
+                            description: |
+                              Name of the uploaded file.
+                          path_id:
+                            type: string
+                            description: |
+                              A representation of the path of the file within the
+                              repository of user-uploaded files.  If the `path_id` of a
+                              file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:
+                              `{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.
+                          size:
+                            type: integer
+                            description: |
+                              Size of the file in bytes.
+                          create_time:
+                            type: integer
+                            description: |
+                              Time when the attachment was uploaded.
+                          messages:
+                            type: array
+                            description: |
+                              Contains basic details on any Zulip messages that have been
+                              sent referencing this [uploaded file](/api/upload-file).
+                              This includes messages sent by any user in the Zulip
+                              organization who sent a message containing a link to the
+                              uploaded file.
+                            items:
+                              type: object
+                    upload_space_used:
+                      type: integer
+                      description: |
+                        The total size of all files uploaded by in the organization,
+                        in bytes.
+                - example:
+                    {
+                        "result": "success",
+                        "msg": "",
+                        "attachments": [
+                            {
+                                "id": 1,
+                                "name": "166050.jpg",
+                                "path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg",
+                                "size": 571946,
+                                "create_time": 1588145417000,
+                                "messages": [
+                                    {
+                                        "id": 102,
+                                        "name": 1588145424000
+                                    },
+                                    {
+                                        "id": 103,
+                                        "name": 1588145448000
+                                    }
+                                ]
+                            }
+                        ],
+                        "upload_space_used": 571946
+                    }
   /messages:
     get:
       operationId: get_messages

zerver/tests/test_openapi.py

@@ -206,9 +206,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         '/users/me/status',
 
         #### These realm administration settings are valuable to document:
-        # List all files uploaded by current user.  May want to add support
-        # for a larger list available to administrators?
-        '/attachments',
         # Delete a file uploaded by current user.
         '/attachments/{attachment_id}',
         # List data exports for organization (GET) or request one (POST)