api docs: Migrate POST /user_uploads to OpenAPI.

templates/zerver/api/arguments.json

@@ -38,13 +38,5 @@
             "required": false,
             "example": "change_all"
         }
-    ],
-    "upload-file.md": [
-        {
-            "argument": "file",
-            "description": "File to be uploaded.",
-            "required": true,
-            "example": "See code examples above."
-        }
     ]
 }

templates/zerver/api/fixtures.json

@@ -120,11 +120,6 @@
         "msg": "You don't have permission to edit this message",
         "result": "error"
     },
-    "upload-file": {
-        "msg": "",
-        "result": "success",
-        "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt"
-    },
     "user-not-authorized-error": {
         "code": "BAD_REQUEST",
         "msg": "User not authorized for this query",

templates/zerver/api/upload-file.md

@@ -2,7 +2,7 @@
 
 Upload a single file and get the corresponding URI.
 
-`POST {{ api_url}}/v1/user_uploads`
+`POST {{ api_url }}/v1/user_uploads`
 
 ## Usage examples
 <div class="code-section" markdown="1">
@@ -13,7 +13,7 @@ Upload a single file and get the corresponding URI.
 
 <div data-language="python" markdown="1">
 
-{generate_code_example(python)|upload-file|example}
+{generate_code_example(python)|/user_uploads:post|example}
 
 </div>
 
@@ -23,7 +23,8 @@ Upload a single file and get the corresponding URI.
 
 ## Arguments
 
-{generate_api_arguments_table|arguments.json|upload-file.md}
+The file to upload must be provided, and it should be placed in the request's
+body as `multipart` media type.
 
 ## Maximum file size
 
@@ -44,4 +45,4 @@ to 25MB.
 
 A typical successful JSON response may look like:
 
-{generate_code_example|upload-file|fixture}
+{generate_code_example|/user_uploads:post|fixture(200)}

zerver/lib/api_test_helpers.py

@@ -433,9 +433,7 @@ def upload_file(client):
     )
     # {code_example|end}
 
-    fixture = FIXTURES['upload-file']
+    validate_against_openapi_schema(result, '/user_uploads', 'post', '200')
-    test_against_fixture(result, fixture, check_if_equal=['msg', 'result'],
-                         check_if_exists=['uri'])
 
 def get_stream_topics(client, stream_id):
     # type: (Client, int) -> None
@@ -480,7 +478,7 @@ TEST_FUNCTIONS = {
     '/users:get': get_members,
     '/register:post': register_queue,
     '/events:delete': deregister_queue,
-    'upload-file': upload_file,
+    '/user_uploads:post': upload_file,
     '/users/me/{stream_id}/topics:get': get_stream_topics
 }
 

zerver/openapi/zulip.yaml

@@ -402,6 +402,37 @@ paths:
                         "rendered": "<p><strong>foo</strong></p>",
                         "result": "success"
                     }
+  /user_uploads:
+    post:
+      description: Upload a single file and get the corresponding URI.
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              properties:
+                filename:
+                  type: string
+                  format: binary
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    uri:
+                      type: string
+                      description: The URI of the uploaded file.
+                - example:
+                    {
+                        "msg": "",
+                        "result": "success",
+                        "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt"
+                    }
   /users:
     get:
       description: Retrieve all users in a realm.