From 0ecdc663b95b423f96179ccb62b6302f2553a7d1 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Thu, 25 Jun 2020 14:34:10 -0700 Subject: [PATCH] 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 | 5 +-- zerver/openapi/python_examples.py | 2 +- zerver/openapi/zulip.yaml | 54 +++++++++++++-------------- 3 files changed, 30 insertions(+), 31 deletions(-) diff --git a/templates/zerver/api/create-stream.md b/templates/zerver/api/create-stream.md index 9b1bbd9261..c854dce376 100644 --- a/templates/zerver/api/create-stream.md +++ b/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 -stream using the `invite_only` and `announce` parameters to that -request. +doesn't yet exist and passing appropriate parameters to define +the initial configuration of the new stream. diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py index 299e2bab0d..aaf5b2b803 100644 --- a/zerver/openapi/python_examples.py +++ b/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( diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 25181c2ac6..8c8734773b 100644 --- a/zerver/openapi/zulip.yaml +++ b/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 - the parameters (see below). + created. The initial [stream settings](/api/update-stream) will be determined + 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 - there was an authorization error, but the response is still considered a - successful one. + as such. When set to `False`, the response will be a 200 and any streams + where the request encountered an authorization error will be listed + 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 - `subscriptions` has to be created (i.e. doesn't exist to begin with), an - announcement will be made notifying that a new stream was created. + If one of the streams specified did not exist previously and is thus craeted + by this call, this determines whether [notification bot](/help/configure-notification-bot) + 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