From b1b0296a2165633b72e6324dfb2a939b28e9a162 Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Wed, 21 Jun 2023 19:31:51 +0200
Subject: [PATCH] api-docs: Update subscription peer_add and peer_remove
 events.

Updates the example for both of these events in the documentation
to be the current version. These were missed when the feature
level 35 updates were made to the API specification for these
events, see commit noted below.

Also, for completeness, adds Changes notes for feature level 35
and feature level 19, for these events.

The feature level 35 changes were made in commit 7ff3859136638d.
The feature level 19 changes were made in commit 00e60c0c91343d.
---
 api_docs/changelog.md     | 12 +++++++-----
 zerver/openapi/zulip.yaml | 38 ++++++++++++++++++++++++++++++++++----
 2 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/api_docs/changelog.md b/api_docs/changelog.md
index b3e330b94e..464c51c9ee 100644
--- a/api_docs/changelog.md
+++ b/api_docs/changelog.md
@@ -1241,8 +1241,10 @@ field with an integer field `invite_to_realm_policy`.
 
 **Feature level 35**
 
-* The peer_add and peer_remove subscription events now have plural
-  versions of `user_ids` and `stream_ids`.
+* [`GET /events`](/api/get-events): The `subscription` events for
+  `peer_add` and `peer_remove` now include `user_ids` and `stream_ids`
+  arrays. Previously, these events included singular `user_id` and
+  `stream_id` integers.
 
 **Feature level 34**
 
@@ -1349,9 +1351,9 @@ No changes; feature level used for Zulip 3.0 release.
 
 **Feature level 19**
 
-* [`GET /events`](/api/get-events): `subscriptions` event with
-  `op="peer_add"` and `op="peer_remove"` now identify the modified
-  stream by a `stream_id` field, replacing the old `name` field.
+* [`GET /events`](/api/get-events): The `subscription` events for
+  `peer_add` and `peer_remove` now identify the modified
+  stream by the `stream_id` field, replacing the old `name` field.
 
 **Feature level 18**
 
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index c84f3c4aaf..ad548e5f91 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -771,6 +771,15 @@ paths:
                                 Event sent to other users when users have been subscribed to
                                 streams. Sent to all users if the stream is public or to only
                                 the existing subscribers if the stream is private.
+
+                                **Changes**: In Zulip 4.0 (feature level 35), the singular
+                                `user_id` and `stream_id` integers included in this event
+                                were replaced with plural `user_ids` and `stream_ids` integer
+                                arrays.
+
+                                In Zulip 3.0 (feature level 19), the `stream_id` field was
+                                added to identify the stream the user subscribed to,
+                                replacing the `name` field.
                               properties:
                                 id:
                                   $ref: "#/components/schemas/EventIdSchema"
@@ -787,12 +796,18 @@ paths:
                                   type: array
                                   description: |
                                     The IDs of the streams to which the user has subscribed.
+
+                                    **Changes**: New in Zulip 4.0 (feature level 35), replacing
+                                    the `stream_id` integer.
                                   items:
                                     type: integer
                                 user_ids:
                                   type: array
                                   description: |
                                     The IDs of the users who subscribed.
+
+                                    **Changes**: New in Zulip 4.0 (feature level 35), replacing
+                                    the `user_id` integer.
                                   items:
                                     type: integer
                               additionalProperties: false
@@ -800,8 +815,8 @@ paths:
                                 {
                                   "type": "subscription",
                                   "op": "peer_add",
-                                  "stream_id": 9,
-                                  "user_id": 12,
+                                  "stream_ids": [9],
+                                  "user_ids": [12],
                                   "id": 0,
                                 }
                             - type: object
@@ -809,6 +824,15 @@ paths:
                                 Event sent to other users when users have been unsubscribed
                                 from streams. Sent to all users if the stream is public or to only
                                 the existing subscribers if the stream is private.
+
+                                **Changes**: In Zulip 4.0 (feature level 35), the singular
+                                `user_id` and `stream_id` integers included in this event
+                                were replaced with plural `user_ids` and `stream_ids` integer
+                                arrays.
+
+                                In Zulip 3.0 (feature level 19), the `stream_id` field was
+                                added to identify the stream the user unsubscribed from,
+                                replacing the `name` field.
                               properties:
                                 id:
                                   $ref: "#/components/schemas/EventIdSchema"
@@ -826,12 +850,18 @@ paths:
                                   description: |
                                     The IDs of the streams from which the users have been
                                     unsubscribed from.
+
+                                    **Changes**: New in Zulip 4.0 (feature level 35), replacing
+                                    the `stream_id` integer.
                                   items:
                                     type: integer
                                 user_ids:
                                   type: array
                                   description: |
                                     The IDs of the users who have been unsubscribed.
+
+                                    **Changes**: New in Zulip 4.0 (feature level 35), replacing
+                                    the `user_id` integer.
                                   items:
                                     type: integer
                               additionalProperties: false
@@ -839,8 +869,8 @@ paths:
                                 {
                                   "type": "subscription",
                                   "op": "peer_remove",
-                                  "stream_id": 9,
-                                  "user_id": 12,
+                                  "stream_ids": [9],
+                                  "user_ids": [12],
                                   "id": 0,
                                 }
                             - type: object