From 7ceb5f6311c094c00c8d6e40c1d842df0dea9936 Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Thu, 19 May 2022 23:24:50 +0200
Subject: [PATCH] api-docs: Add changelog for `stream_id` param to
 `mute-topic`.

Adds a changelog 2.0 entry for adding support for `stream_id`
parameter to the `mute-topic` endpoint. Also, adds Changes note
to the endpoint parameter description, and reorders/clarifies
that at least one (and only one) stream parameter must be provided
by the client and that the `string_id` parameter is preferred.

Fixes #11136.
---
 templates/zerver/api/changelog.md |  3 +++
 zerver/openapi/zulip.yaml         | 25 +++++++++++++++++--------
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/templates/zerver/api/changelog.md b/templates/zerver/api/changelog.md
index d061c10825..82ba8f60d7 100644
--- a/templates/zerver/api/changelog.md
+++ b/templates/zerver/api/changelog.md
@@ -1080,6 +1080,9 @@ No changes; feature level used for Zulip 3.0 release.
 
 ## Changes in Zulip 2.0
 
+* [`PATCH /users/me/subscriptions/muted_topics`](/api/mute-topic):
+  Added support for using stream IDs to specify the stream in which to
+  mute/unmute a topic.
 * [`POST /messages`](/api/send-message): Added support for using user
   IDs and stream IDs for specifying the recipients of a message.
 * [`POST /messages`](/api/send-message), [`POST
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 862fb7a40e..57df8e858f 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -7447,22 +7447,31 @@ paths:
               enum:
                 - stream_id
       parameters:
-        - name: stream
-          in: query
-          description: |
-            The name of the stream to access.
-          schema:
-            type: string
-          example: Denmark
-          required: false
         - name: stream_id
           in: query
           description: |
             The ID of the stream to access.
+
+            Clients must provide either `stream` or `stream_id` as a parameter
+            to this endpoint, but not both.
+
+            **Changes**: New in Zulip 2.0.
           schema:
             type: integer
           example: 43
           required: false
+        - name: stream
+          in: query
+          description: |
+            The name of the stream to access.
+
+            Clients must provide either `stream` or `stream_id` as a parameter
+            to this endpoint, but not both. Clients should use `stream_id`
+            instead of the `stream` parameter when possible.
+          schema:
+            type: string
+          example: Denmark
+          required: false
         - name: topic
           in: query
           description: |