api docs: Correct errors in the stream creation documentation.

* Reordered the settings relevant without stream creation to the top.
* Removed useless/misleading defaults for optional parameters.
* Clarified description of the announce and authorization_errors_fatal settings.
* Clarified that `invite_only` only applies for stream creation.
  (It's annoying to do so for its friends because they are including
   common description content and OpenAPI doesn't have a way to have
   extra content in a place you included something)

Fixes #14705.

templates/zerver/api/create-stream.md

@@ -2,6 +2,5 @@
 
 You can create a stream using Zulip's REST API by submitting a
 [subscribe](/api/subscribe) request with a stream name that
-doesn't yet exist.  You can specify the initial configuration of the
+doesn't yet exist and passing appropriate parameters to define
-stream using the `invite_only` and `announce` parameters to that
+the initial configuration of the new stream.
-request.

zerver/openapi/python_examples.py

@@ -62,7 +62,7 @@ def add_subscriptions(client: Client) -> None:
                                     '200_0')
 
     # {code_example|start}
-    # To subscribe another user to a stream, you may pass in
+    # To subscribe other users to a stream, you may pass
     # the `principals` argument, like so:
     user_id = 25
     result = client.add_subscriptions(

zerver/openapi/zulip.yaml

@@ -2369,8 +2369,8 @@ paths:
         `POST {{ api_url }}/v1/users/me/subscriptions`
 
         If any of the specified streams do not exist, they are automatically
-        created, and configured using the `invite_only` setting specified in
+        created.  The initial [stream settings](/api/update-stream) will be determined
-        the parameters (see below).
+        by the optional parameters like `invite_only` detailed below.
       parameters:
       - name: subscriptions
         in: query
@@ -2380,25 +2380,12 @@ paths:
           exist a new stream is created. The description of the stream created can
           be specified by setting the dictionary key `description` with an
           appropriate value.
-
-
-          **Note**: This parameter is called `streams` and not `subscriptions`
-          in our Python API."
         schema:
           type: array
           items:
             type: object
         example: [{"name": "Verona", "description": "Italian City"}]
         required: true
-      - name: invite_only
-        in: query
-        description: |
-          A boolean specifying whether the streams specified in `subscriptions`
-          are invite-only or not.
-        schema:
-          type: boolean
-          default: false
-        example: true
       - $ref: '#/components/parameters/Principals'
       - name: authorization_errors_fatal
         in: query
@@ -2406,25 +2393,40 @@ paths:
           A boolean specifying whether authorization errors (such as when the
           requesting user is not authorized to access a private stream) should be
           considered fatal or not. When `True`, an authorization error is reported
-          as such. When set to `False`, the returned JSON payload indicates that
+          as such. When set to `False`, the response will be a 200 and any streams
-          there was an authorization error, but the response is still considered a
+          where the request encountered an authorization error will be listed
-          successful one.
+          in the `unauthorized` key.
         schema:
           type: boolean
           default: true
         example: false
-      - $ref: '#/components/parameters/HistoryPublicToSubscribers'
-      - $ref: '#/components/parameters/StreamPostPolicy'
-      - $ref: '#/components/parameters/MessageRetentionDays'
       - name: announce
         in: query
         description: |
-          If `announce` is `True` and one of the streams specified in
+          If one of the streams specified did not exist previously and is thus craeted
-          `subscriptions` has to be created (i.e. doesn't exist to begin with), an
+          by this call, this determines whether [notification bot](/help/configure-notification-bot)
-          announcement will be made notifying that a new stream was created.
+          will send an announcement about the new stream's creation.
         schema:
           type: boolean
+          default: false
         example: true
+      - name: invite_only
+        in: query
+        description: |
+          As described above, this endpoint will create a new stream if passed
+          a stream name that doesn't already exist.  This parameters and the ones
+          that follow are used to request an initial configuration of a created
+          stream; they are ignored for streams that already exist.
+
+          This parameter determines whether any newly created streams will be
+          private streams.
+        schema:
+          type: boolean
+          default: false
+        example: true
+      - $ref: '#/components/parameters/HistoryPublicToSubscribers'
+      - $ref: '#/components/parameters/StreamPostPolicy'
+      - $ref: '#/components/parameters/MessageRetentionDays'
       responses:
         '200':
           description: Success.
@@ -4899,7 +4901,7 @@ components:
               type: string
             description: |
               A list of names of streams that the requesting user/bot was not
-              authorized to subscribe to.
+              authorized to subscribe to.  Only present if `authorization_errors_fatal=false`.
     InvalidApiKeyError:
       allOf:
       - $ref: '#/components/schemas/JsonError'
@@ -5116,7 +5118,6 @@ components:
         option in documentation.
       schema:
         type: boolean
-        default: None
       example: false
       required: false
 
@@ -5177,7 +5178,6 @@ components:
           oneOf:
             - type: string
             - type: integer
-        default: []
       example: ['ZOE@zulip.com']
     ReactionType:
       name: reaction_type