api docs: Migrate POST /messages to OpenAPI.

templates/zerver/api/arguments.json

@@ -1,30 +1,4 @@
 {
-    "send-message.md": [
-        {
-            "argument": "type",
-            "description": "The type of message to be sent. `stream` for a stream message and `private` for a private message.",
-            "required": true,
-            "example": "stream"
-        },
-        {
-            "argument": "to",
-            "description": "A string identifying the stream.",
-            "required": true,
-            "example": "Denmark"
-        },
-        {
-            "argument": "subject",
-            "description": "The topic of the message. Only required if `type` is `stream`. Defaults to `None`. Maximum length of 60 characters.",
-            "required": false,
-            "example": "Castle"
-        },
-        {
-            "argument": "content",
-            "description": "The content of the message. Maximum message size of 10000 bytes.",
-            "required": true,
-            "example": "Hello"
-        }
-    ],
     "get-all-streams.md": [
         {
             "argument": "include_public",

templates/zerver/api/fixtures.json

@@ -249,11 +249,6 @@
         "msg": "Invalid API key",
         "result": "error"
     },
-    "invalid-pm-recipient-error": {
-        "code": "BAD_REQUEST",
-        "msg": "Invalid email 'eeshan@zulip.com'",
-        "result": "error"
-    },
     "invalid-stream-error": {
         "code": "BAD_REQUEST",
         "msg": "Invalid stream name 'nonexistent'",
@@ -303,11 +298,6 @@
         "rendered": "<p><strong>foo</strong></p>",
         "result": "success"
     },
-    "send-message": {
-        "id": 134,
-        "msg": "",
-        "result": "success"
-    },
     "successful-response-empty": {
         "msg": "",
         "result": "success"

templates/zerver/api/send-message.md

@@ -38,7 +38,7 @@ curl {{ api_url }}/v1/messages \
 
 <div data-language="python" markdown="1">
 
-{generate_code_example(python)|send-message|example}
+{generate_code_example(python)|/messages:post|example}
 
 </div>
 
@@ -117,7 +117,7 @@ zulip(config).then((client) => {
 
 ## Arguments
 
-{generate_api_arguments_table|arguments.json|send-message.md}
+{generate_api_arguments_table|zulip.yaml|/messages:post}
 
 ## Response
 
@@ -128,14 +128,14 @@ zulip(config).then((client) => {
 #### Example response
 A typical successful JSON response may look like:
 
-{generate_code_example|send-message|fixture}
+{generate_code_example|/messages:post|fixture(200)}
 
 A typical failed JSON response for when a stream message is sent to a stream
 that does not exist:
 
-{generate_code_example|nonexistent-stream-error|fixture}
+{generate_code_example|/messages:post|fixture(400_non_existing_stream)}
 
 A typical failed JSON response for when a private message is sent to a user
 that does not exist:
 
-{generate_code_example|invalid-pm-recipient-error|fixture}
+{generate_code_example|/messages:post|fixture(400_non_existing_user)}

zerver/lib/api_test_helpers.py

@@ -307,9 +307,7 @@ def send_message(client):
     result = client.send_message(request)
     # {code_example|end}
 
-    fixture = FIXTURES['send-message']
+    validate_against_openapi_schema(result, '/messages', 'post', '200')
-    test_against_fixture(result, fixture, check_if_equal=['result'],
-                         check_if_exists=['id'])
 
     # test that the message was actually sent
     message_id = result['id']
@@ -331,8 +329,7 @@ def send_message(client):
     result = client.send_message(request)
     # {code_example|end}
 
-    test_against_fixture(result, fixture, check_if_equal=['result'],
+    validate_against_openapi_schema(result, '/messages', 'post', '200')
-                         check_if_exists=['id'])
 
     # test that the message was actually sent
     message_id = result['id']
@@ -356,8 +353,8 @@ def test_nonexistent_stream_error(client):
     }
     result = client.send_message(request)
 
-    fixture = FIXTURES['nonexistent-stream-error']
+    validate_against_openapi_schema(result, '/messages', 'post',
-    test_against_fixture(result, fixture)
+                                    '400_non_existing_stream')
 
 def test_private_message_invalid_recipient(client):
     # type: (Client) -> None
@@ -368,8 +365,8 @@ def test_private_message_invalid_recipient(client):
     }
     result = client.send_message(request)
 
-    fixture = FIXTURES['invalid-pm-recipient-error']
+    validate_against_openapi_schema(result, '/messages', 'post',
-    test_against_fixture(result, fixture)
+                                    '400_non_existing_user')
 
 def update_message(client, message_id):
     # type: (Client, int) -> None
@@ -503,7 +500,7 @@ def test_invalid_stream_error(client):
 
 TEST_FUNCTIONS = {
     'render-message': render_message,
-    'send-message': send_message,
+    '/messages:post': send_message,
     '/messages/{message_id}:patch': update_message,
     'get-stream-id': get_stream_id,
     'get-subscribed-streams': list_subscriptions,

zerver/openapi/zulip.yaml

@@ -24,6 +24,97 @@ servers:
 # Endpoint definitions
 #######################
 paths:
+  /messages:
+    post:
+      description: Send a message.
+      parameters:
+      - name: type
+        in: query
+        description: The type of message to be sent. `private` for a private
+          message and `stream` for a stream message.
+        schema:
+          type: string
+          enum:
+            - private
+            - stream
+        example: private
+        required: true
+      - name: to
+        in: query
+        description: The destination stream, or a CSV/JSON-encoded list
+          containing the usernames (emails) of the recipients.
+        schema:
+          type: string
+        example: aaron@zulip.com, iago@zulip.com
+        required: true
+      - name: subject
+        in: query
+        description: The topic of the message. Only required if `type` is
+          `stream`, ignored otherwise. Maximum length of 60 characters.
+        schema:
+          type: string
+          default:
+        example: Castle
+      - name: content
+        in: query
+        description: The content of the message. Maximum message size of
+          10000 bytes.
+        schema:
+          type: string
+        example: Hello
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    id:
+                      type: integer
+                      description: The ID assigned to the message sent.
+                - example:
+                    {
+                        "msg": "",
+                        "id": 42,
+                        "result": "success"
+                    }
+        '400_non_existing_stream':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/CodedError'
+                - properties:
+                    stream:
+                      type: string
+                      description: The name of the stream that could not be
+                        found.
+                - example:
+                    {
+                        "code": "STREAM_DOES_NOT_EXIST",
+                        "msg": "Stream 'nonexistent_stream' does not exist",
+                        "result": "error",
+                        "stream": "nonexistent_stream"
+                    }
+        '400_non_existing_user':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/CodedError'
+                - example:
+                    {
+                        "code": "BAD_REQUEST",
+                        "msg": "Invalid email 'eeshan@zulip.com'",
+                        "result": "error"
+                    }
   /messages/{message_id}:
     patch:
       description: Edit a message that has already been sent.
@@ -287,6 +378,7 @@ paths:
                         ]
                     }
 
+
 components:
   #######################
   # Security definitions
@@ -335,6 +427,13 @@ components:
             - error
           msg:
             type: string
+    CodedError:
+      allOf:
+      - $ref: '#/components/schemas/JsonError'
+      - properties:
+          code:
+            type: string
+            description: A string that identifies the error.
     AddSubscriptionsResponse:
       allOf:
       - $ref: '#/components/schemas/JsonSuccess'