api_docs: Add documentation for update_stream.

templates/zerver/api/update-stream.md

@@ -0,0 +1,51 @@
+# Update stream
+
+Configure the stream with the ID `stream_id`.  This endpoint supports
+an organization administrator editing any property of a stream,
+including:
+
+* Stream [name](/help/rename-a-stream) and [description](/help/change-the-stream-description)
+* Stream [permissions](/help/stream-permissions), including
+  [privacy](/help/change-the-privacy-of-a-stream) and [who can
+  send](/help/announcement-only-streams).
+
+`PATCH {{ api_url }}/v1/streams/{stream_id}`
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/streams/{stream_id}:patch|example}
+
+{tab|curl}
+
+``` curl
+curl -X PATCH {{ api_url }}/v1/streams/{stream_id} \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d 'new_name="Manchester United"' \
+    -d 'description="Biggest club in the world"' \
+    -d 'is_private=false'
+```
+
+{end_tabs}
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/streams/{stream_id}:patch}
+
+## Response
+
+#### Return values
+
+* `stream_id`: The ID of the stream to be updated.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/streams/{stream_id}:patch|fixture(200)}
+
+An example JSON response for when the supplied stream does not exist:
+
+{generate_code_example|/streams/{stream_id}:patch|fixture(400)}

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

@@ -24,6 +24,7 @@
 * [Create a stream](/api/create-stream)
 * [Get stream ID](/api/get-stream-id)
 * [Delete a stream](/api/delete-stream)
+* [Update a stream](/api/update-stream)
 
 #### Users
 

zerver/lib/api_test_helpers.py

@@ -261,14 +261,19 @@ def get_streams(client):
 
 def update_stream(client, stream_id):
     # type: (Client, int) -> None
+
+    # {code_example|start}
+    # Update the stream by a given ID
     request = {
         'stream_id': stream_id,
-        'content': 'Venice is the capital of Italy',
-        'subject': 'Italy'
+        'is_announcement_only': True,
+        'is_private': True,
     }
 
     result = client.update_stream(request)
+    # {code_example|end}
 
+    validate_against_openapi_schema(result, '/streams/{stream_id}', 'patch', '200')
     assert result['result'] == 'success'
 
 def get_user_groups(client):

zerver/openapi/zulip.yaml

@@ -2079,6 +2079,80 @@ paths:
                         "msg": "Invalid stream id",
                         "result": "error"
                     }
+    patch:
+      description: Update the stream with the given ID.
+      parameters:
+      - name: stream_id
+        in: path
+        description: The ID of the stream to be updated.
+        schema:
+          type: integer
+        example: 42
+        required: true
+      - name: description
+        in: query
+        description: The new description for the stream.
+        schema:
+          type: string
+        example: "This stream is related to football dicsussions."
+        required: false
+      - name: new_name
+        in: query
+        description: The new name for the stream.
+        schema:
+          type: string
+        example: "Italy"
+        required: false
+      - name: is_private
+        in: query
+        description: The new state of the stream.
+        schema:
+          type: boolean
+        example: true
+        required: false
+      - name: is_announcement_only
+        in: query
+        description: The new state for the announcements.
+        schema:
+          type: boolean
+        example: true
+        required: false
+      - name: history_public_to_subscribers
+        in: query
+        description: The new state for the history_public_to_subscribers.
+        schema:
+          type: boolean
+        example: true
+        required: false
+
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - example:
+                      {
+                          "msg": "",
+                          "result": "success"
+                      }
+        '400':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonError'
+                - example:
+                    {
+                        "code": "BAD_REQUEST",
+                        "msg": "Invalid stream id",
+                        "result": "error"
+                    }
   /typing:
     post:
       description: Send an event indicating that the user has started or