api docs: Document the POST /users/me/subscriptions/properties endpoint.

zerver/lib/api_test_helpers.py

@@ -374,6 +374,28 @@ def mark_topic_as_read(client):
 
     validate_against_openapi_schema(result, '/mark_stream_as_read', 'post', '200')
 
+def update_subscription_settings(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Update the user's subscription in stream #1 to pin it to the top of the
+    # stream list; and in stream #3 to have the hex color "f00"
+    request = [{
+        'stream_id': 1,
+        'property': 'pin_to_top',
+        'value': True
+    }, {
+        'stream_id': 3,
+        'property': 'color',
+        'value': 'f00'
+    }]
+    result = client.update_subscription_settings(request)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result,
+                                    '/users/me/subscriptions/properties',
+                                    'POST', '200')
+
 def render_message(client):
     # type: (Client) -> None
 
@@ -759,6 +781,7 @@ TEST_FUNCTIONS = {
     '/users/{email}/presence:get': get_user_presence,
     '/users/me/subscriptions:delete': remove_subscriptions,
     '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic,
+    '/users/me/subscriptions/properties:post': update_subscription_settings,
     '/users:get': get_members,
     '/realm/emoji:get': get_realm_emoji,
     '/realm/filters:get': get_realm_filters,
@@ -860,6 +883,7 @@ def test_streams(client, nonadmin_client):
     get_subscribers(client)
     remove_subscriptions(client)
     toggle_mute_topic(client)
+    update_subscription_settings(client)
     get_stream_topics(client, 1)
 
     test_user_not_authorized_error(nonadmin_client)