api docs: Migrate POST /users to OpenAPI.

templates/zerver/api/arguments.json

@@ -39,32 +39,6 @@
             "example": "change_all"
         }
     ],
-    "create-user.md": [
-        {
-            "argument": "email",
-            "description": "The email address of the new user.",
-            "required": true,
-            "example": "newbie@zulip.com"
-        },
-        {
-            "argument": "password",
-            "description": "The password of the new user.",
-            "required": true,
-            "example": "abdec@7982"
-        },
-        {
-            "argument": "full_name",
-            "description": "The full name of the new user.",
-            "required": true,
-            "example": "John Smith"
-        },
-        {
-            "argument": "short_name",
-            "description": "The short name of the new user.",
-            "required": true,
-            "example": "jsmith"
-        }
-    ],
     "remove-subscriptions.md": [
         {
             "argument": "subscriptions",

templates/zerver/api/create-user.md

@@ -31,7 +31,7 @@ curl {{ api_url }}/v1/users \
 
 <div data-language="python" markdown="1">
 
-{generate_code_example(python)|create-user|example(admin_config=True)}
+{generate_code_example(python)|/users:post|example(admin_config=True)}
 
 </div>
 
@@ -64,7 +64,7 @@ zulip(config).then((client) => {
 
 ## Arguments
 
-{generate_api_arguments_table|arguments.json|create-user.md}
+{generate_api_arguments_table|zulip.yaml|/users:post}
 
 ## Response
 
@@ -72,9 +72,9 @@ zulip(config).then((client) => {
 
 A typical successful JSON response may look like:
 
-{generate_code_example|successful-response-empty|fixture}
+{generate_code_example|/users:post|fixture(200)}
 
 A typical JSON response for when another user with the same
 email address already exists in the realm:
 
-{generate_code_example|email_already_used_error|fixture}
+{generate_code_example|/users:post|fixture(400)}

templates/zerver/api/fixtures.json

@@ -5,10 +5,6 @@
         "queue_id": "1518820930:1",
         "result": "error"
     },
-    "email_already_used_error": {
-        "msg": "Email 'newbie@zulip.com' already in use",
-        "result": "error"
-    },
     "get-profile": {
         "client_id": "74c768b081076fdb3c4326256c17467e",
         "email": "iago@zulip.com",

zerver/lib/api_test_helpers.py

@@ -113,14 +113,12 @@ def create_user(client):
     result = client.create_user(request)
     # {code_example|end}
 
-    fixture = FIXTURES['successful-response-empty']
-    test_against_fixture(result, fixture)
+    validate_against_openapi_schema(result, '/users', 'post', '200')
 
     # Test "Email already used error"
     result = client.create_user(request)
 
-    fixture = FIXTURES['email_already_used_error']
-    test_against_fixture(result, fixture)
+    validate_against_openapi_schema(result, '/users', 'post', '400')
 
 def get_members(client):
     # type: (Client) -> None
@@ -474,7 +472,7 @@ TEST_FUNCTIONS = {
     '/get_stream_id:get': get_stream_id,
     'get-subscribed-streams': list_subscriptions,
     '/streams:get': get_streams,
-    'create-user': create_user,
+    '/users:post': create_user,
     'get-profile': get_profile,
     'add-subscriptions': add_subscriptions,
     'remove-subscriptions': remove_subscriptions,

zerver/openapi/zulip.yaml

@@ -467,6 +467,58 @@ paths:
                         "msg": "",
                         "result": "success"
                     }
+    post:
+      description: Create a new user in a realm.
+      parameters:
+      - name: email
+        in: query
+        description: The email address of the new user.
+        schema:
+           type: string
+        example: newbie@zulip.com
+        required: true
+      - name: password
+        in: query
+        description: The password of the new user.
+        schema:
+           type: string
+        example: abdec@7982
+        required: true
+      - name: full_name
+        in: query
+        description: The full name of the new user.
+        schema:
+           type: string
+        example: John Smith
+        required: true
+      - name: short_name
+        in: query
+        description: The short name of the new user.
+        schema:
+           type: string
+        example: jsmith
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JsonSuccess'
+        '400':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonError'
+                - example:
+                    {
+                        "msg": "Email 'newbie@zulip.com' already in use",
+                        "result": "error"
+                    }
   /users/me/{stream_id}/topics:
     get:
       description: Get all the topics in a specific stream.