api_docs: Add documentation for delete_stream.

templates/zerver/api/delete-stream.md

@@ -0,0 +1,43 @@
+# Delete stream
+
+[Delete the stream](/help/delete-a-stream) with the ID `stream_id`.
+
+`DELETE {{ api_url }}/v1/streams/{stream_id}`
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/streams/{stream_id}:delete|example}
+
+{tab|curl}
+
+``` curl
+curl -X DELETE {{ api_url }}/v1/streams/{stream_id} \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+```
+
+{end_tabs}
+
+## Arguments
+
+**Note**: The following arguments are all URL query parameters.
+
+{generate_api_arguments_table|zulip.yaml|/streams/{stream_id}:delete}
+
+## Response
+
+#### Return values
+
+* `stream_id`: The ID of a stream.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/streams/{stream_id}:delete|fixture(200)}
+
+An example JSON response for when the supplied stream does not exist:
+
+{generate_code_example|/streams/{stream_id}:delete|fixture(400)}

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

@@ -23,6 +23,7 @@
 * [Topic muting](/api/mute-topics)
 * [Create a stream](/api/create-stream)
 * [Get stream ID](/api/get-stream-id)
+* [Delete a stream](/api/delete-stream)
 
 #### Users
 

zerver/lib/api_test_helpers.py

@@ -229,8 +229,11 @@ def get_stream_id(client):
 def delete_stream(client, stream_id):
     # type: (Client, int) -> None
 
+    # {code_example|start}
+    # Delete the stream named 'new stream'
+    stream_id = client.get_stream_id('new stream')['stream_id']
     result = client.delete_stream(stream_id)
-
+    # {code_example|end}
     validate_against_openapi_schema(result, '/streams/{stream_id}', 'delete', '200')
 
     assert result['result'] == 'success'

zerver/openapi/zulip.yaml

@@ -2049,7 +2049,8 @@ paths:
         description: The ID of the stream to be deleted.
         schema:
           type: integer
-          required: true
+        example: 42
+        required: true
       security:
       - basicAuth: []
       responses:
@@ -2058,12 +2059,19 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/JsonSuccess'
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - example:
+                      {
+                          "msg": "",
+                          "result": "success"
+                      }
         '400':
           description: Bad request.
           content:
             application/json:
               schema:
+                allOf:
                 - $ref: '#/components/schemas/JsonError'
                 - example:
                     {