diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index f1570c1396..052d929ffd 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -96,7 +96,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ApiKeyResponse" + allOf: + - $ref: "#/components/schemas/ApiKeyResponse" + - $ref: "#/components/schemas/SuccessDescription" /dev_fetch_api_key: post: operationId: dev_fetch_api_key @@ -130,7 +132,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ApiKeyResponse" + allOf: + - $ref: "#/components/schemas/ApiKeyResponse" + - $ref: "#/components/schemas/SuccessDescription" /events: get: operationId: get_events @@ -182,6 +186,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -3847,7 +3852,11 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/BadEventQueueIdError" + allOf: + - $ref: "#/components/schemas/BadEventQueueIdError" + - description: | + If the target event queue has been garbage collected, you'll get the + following error response delete: operationId: delete_queue summary: Delete an event queue @@ -3864,13 +3873,19 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" "400": description: Bad request. content: application/json: schema: - $ref: "#/components/schemas/BadEventQueueIdError" + allOf: + - $ref: "#/components/schemas/BadEventQueueIdError" + - description: | + A typical JSON response for when the `queue_id` is non-existent or the + associated queue has already been deleted /get_stream_id: get: operationId: get_stream_id @@ -3897,6 +3912,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -3919,6 +3935,7 @@ paths: "msg": "Invalid stream name 'nonexistent'", "result": "error", } + description: An example JSON response for when the supplied stream does not exist /mark_all_as_read: post: operationId: mark_all_as_read @@ -3934,7 +3951,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" /mark_stream_as_read: post: operationId: mark_stream_as_read @@ -3957,7 +3976,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" /mark_topic_as_read: post: operationId: mark_topic_as_read @@ -3988,7 +4009,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" /attachments: get: operationId: get_attachments @@ -4006,6 +4029,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4171,6 +4195,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4371,6 +4396,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4393,7 +4419,11 @@ paths: application/json: schema: oneOf: - - $ref: "#/components/schemas/NonExistingStreamError" + - allOf: + - $ref: "#/components/schemas/NonExistingStreamError" + - description: | + A typical failed JSON response for when a stream message is sent to a stream + that does not exist - allOf: - $ref: "#/components/schemas/CodedError" - example: @@ -4402,6 +4432,9 @@ paths: "msg": "Invalid email 'eeshan@zulip.com'", "result": "error", } + description: | + A typical failed JSON response for when a private message is sent to a user + that does not exist /messages/{message_id}/history: get: operationId: get_message_history @@ -4426,6 +4459,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4509,7 +4543,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/InvalidMessageError" + allOf: + - $ref: "#/components/schemas/InvalidMessageError" + - description: An example JSON response for when the specified message does not exist /messages/flags: post: operationId: update_message_flags @@ -4564,6 +4600,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4595,6 +4632,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4652,6 +4690,7 @@ paths: "msg": "Invalid emoji code", "code": "BAD_REQUEST", } + description: An example JSON error response for when the emoji code is invalid delete: operationId: remove_reaction @@ -4694,6 +4733,7 @@ paths: "msg": "Invalid message(s)", "code": "BAD_REQUEST", } + description: An example JSON error response for when the emoji code is invalid /messages/matches_narrow: get: operationId: check_messages_match_narrow @@ -4749,6 +4789,7 @@ paths: application/json: schema: allOf: + - $ref: "#/components/schemas/SuccessDescription" - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: @@ -4815,6 +4856,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -4834,7 +4876,12 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/InvalidMessageError" + allOf: + - $ref: "#/components/schemas/InvalidMessageError" + - description: | + An example JSON response for when the specified message does not exist or it + is not visible to the user making the query (e.g. it was a PM between other + two users) patch: operationId: update_message summary: Edit a message @@ -4921,7 +4968,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" "400": description: Bad request. content: @@ -4943,6 +4992,9 @@ paths: "msg": "You don't have permission to edit this message", "result": "error", } + description: | + A typical JSON response for when one doesn't have the permission to + edit a particular message delete: operationId: delete_message summary: Delete a message @@ -4963,17 +5015,24 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" "400": description: Bad request. content: application/json: schema: oneOf: - - $ref: "#/components/schemas/InvalidMessageError" + - allOf: + - $ref: "#/components/schemas/InvalidMessageError" + - description: An example JSON response for when the specified message does not exist - allOf: - $ref: "#/components/schemas/CodedError" - - example: + - description: | + An example JSON response for when the user making the query does not + have permission to delete the message + example: { "code": "BAD_REQUEST", "msg": "You don't have permission to delete this message", @@ -5015,6 +5074,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5061,6 +5121,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5100,6 +5161,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5235,6 +5297,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5258,7 +5321,9 @@ paths: "msg": "Email 'newbie@zulip.com' already in use", "result": "error", } - + description: | + A typical JSON response for when another user with the same + email address already exists in the realm /users/{user_id}/reactivate: post: operationId: reactivate_user @@ -5281,6 +5346,7 @@ paths: application/json: schema: allOf: + - $ref: "#/components/schemas/SuccessDescription" - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} @@ -5323,6 +5389,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5389,6 +5456,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5585,6 +5653,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request. @@ -5598,6 +5667,9 @@ paths: "msg": "Cannot deactivate the only organization owner", "result": "error", } + description: | + An example JSON error response when attempting to deactivate the only + organization owner in an organization /users/me/{stream_id}/topics: get: operationId: get_stream_topics @@ -5617,6 +5689,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -5661,6 +5734,9 @@ paths: "msg": "Invalid stream id", "result": "error", } + description: | + An example JSON response for when the user is attempting to fetch the topics + of a non-existing stream (or also a private stream they don't have access to) /users/me/subscriptions: get: operationId: get_subscriptions @@ -5683,6 +5759,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" # TODO: Is this the best way to declare required elements in 200 responses? - required: - subscriptions @@ -5814,6 +5891,7 @@ paths: oneOf: - allOf: - $ref: "#/components/schemas/AddSubscriptionsResponse" + - $ref: "#/components/schemas/SuccessDescription" - example: { "already_subscribed": {}, @@ -5831,6 +5909,9 @@ paths: "result": "success", "subscribed": {}, } + description: | + A typical successful JSON response when the user is already subscribed to + the streams specified "400": description: Success. content: @@ -5844,6 +5925,9 @@ paths: "msg": "Unable to access stream (private_stream).", "result": "error", } + description: | + A typical response for when the requesting user does not have access to + a private stream and `authorization_errors_fatal` is `True` - allOf: - $ref: "#/components/schemas/AddSubscriptionsResponse" - example: @@ -5854,6 +5938,9 @@ paths: "subscribed": {}, "unauthorized": ["private_stream"], } + description: | + A typical response for when the requesting user does not have access to + a private stream and `authorization_errors_fatal` is `False` patch: operationId: update_subscriptions summary: Update subscriptions @@ -5911,6 +5998,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - required: - subscribed - already_subscribed @@ -6002,6 +6090,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6032,7 +6121,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/NonExistingStreamError" + allOf: + - $ref: "#/components/schemas/NonExistingStreamError" + - description: A typical failed JSON response for when the target stream does not exist /users/me/subscriptions/muted_topics: patch: operationId: mute_topic @@ -6088,7 +6179,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" "400": description: Bad request. content: @@ -6099,10 +6192,16 @@ paths: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Topic already muted", "result": "error"} + description: | + An example JSON response for when an `add` operation is requested for a topic + that has already been muted - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Topic is not muted", "result": "error"} + description: | + An example JSON response for when a `remove` operation is requested for a + topic that had not been previously muted /users/me/muted_users/{muted_user_id}: post: operationId: mute_user @@ -6149,6 +6248,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request. @@ -6159,13 +6259,16 @@ paths: - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Cannot mute self", "result": "error"} + description: An example JSON response for when the user is yourself - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "No such user", "result": "error"} + description: An example JSON response for when the user is nonexistent or inaccessible - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "User already muted", "result": "error"} + description: An example JSON response for when the user is already muted delete: operationId: unmute_user summary: Unmute a user @@ -6186,6 +6289,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request. @@ -6196,9 +6300,11 @@ paths: - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "No such user", "result": "error"} + description: An example JSON response for when the user is nonexistent or inaccessible - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "User is not muted", "result": "error"} + description: An example JSON response for when the user is not previously muted /users/{user_id}/subscriptions/{stream_id}: get: @@ -6222,7 +6328,9 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false + description: MANUALLY properties: result: {} msg: {} @@ -6267,7 +6375,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" /realm/emoji: get: @@ -6286,6 +6396,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6331,6 +6442,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6450,7 +6562,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" post: operationId: create_custom_profile_field summary: Create a custom profile field @@ -6525,6 +6639,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6591,6 +6706,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6710,6 +6826,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6787,6 +6904,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -6918,6 +7036,7 @@ paths: "msg": "Guests cannot be organization administrators", "code": "BAD_REQUEST", } + description: A typical unsuccessful JSON response delete: operationId: deactivate_user @@ -6941,6 +7060,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request @@ -6954,6 +7074,9 @@ paths: "msg": "Cannot deactivate the only organization owner", "result": "error", } + description: | + An example JSON error response when attempting to deactivate the only + organization owner in an organization /realm/linkifiers: get: operationId: get_linkifiers @@ -6978,6 +7101,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -7038,6 +7162,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -7073,7 +7198,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" patch: operationId: update_linkifier summary: Update a linkifier @@ -7103,7 +7230,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" /realm/playgrounds: post: operationId: add_code_playground @@ -7152,6 +7281,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -7188,7 +7318,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" /register: post: operationId: register_queue @@ -7294,6 +7426,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -9249,6 +9382,7 @@ paths: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false + description: A typical successful JSON response for a single-organization server may look like properties: result: {} msg: {} @@ -9634,6 +9768,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -9864,6 +9999,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -10002,6 +10138,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -10090,6 +10227,10 @@ paths: "msg": "User not authorized for this query", "result": "error", } + description: | + An example JSON response for when the user is not authorized to use the + `include_all_active` parameter (i.e. because they are not an organization + administrator) /streams/{stream_id}: delete: operationId: archive_stream @@ -10109,6 +10250,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request. @@ -10123,6 +10265,7 @@ paths: "msg": "Invalid stream id", "result": "error", } + description: An example JSON response for when the supplied stream does not exist patch: operationId: update_stream summary: Update a stream @@ -10194,6 +10337,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request. @@ -10208,6 +10352,7 @@ paths: "msg": "Invalid stream id", "result": "error", } + description: An example JSON response for when the supplied stream does not exist /typing: post: operationId: set_typing_status @@ -10302,7 +10447,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" "400": description: Bad request. content: @@ -10316,6 +10463,7 @@ paths: "msg": "Cannot send to multiple streams", "result": "error", } + description: An example JSON error response for when user sends to multiple streams /user_groups/create: post: @@ -10364,6 +10512,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"msg": "", "result": "success"} "400": description: Bad request. @@ -10378,6 +10527,7 @@ paths: "code": "BAD_REQUEST", "msg": "Invalid user ID: 500", } + description: An example JSON error response for when the one of the users does not exist /user_groups/{user_group_id}/members: post: operationId: update_user_group_members @@ -10460,6 +10610,7 @@ paths: "msg": "Invalid user group", "result": "error", } + description: An example JSON response when the user group ID is invalid delete: operationId: remove_user_group summary: Delete a user group @@ -10478,6 +10629,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" - example: {"result": "success", "msg": ""} "400": @@ -10493,6 +10645,7 @@ paths: "msg": "Invalid user group", "result": "error", } + description: An example JSON error response for an invalid user group id /user_groups: get: @@ -10511,6 +10664,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -10623,6 +10777,7 @@ paths: schema: type: object additionalProperties: false + description: VERIFY properties: bot_email: type: string @@ -10725,6 +10880,7 @@ paths: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" + - $ref: "#/components/schemas/SuccessDescription" - additionalProperties: false properties: result: {} @@ -12052,6 +12208,8 @@ components: properties: result: type: string + SuccessDescription: + description: A typical successful JSON response may look like JsonSuccess: allOf: - $ref: "#/components/schemas/JsonSuccessBase" @@ -12289,7 +12447,9 @@ components: content: application/json: schema: - $ref: "#/components/schemas/JsonSuccess" + allOf: + - $ref: "#/components/schemas/JsonSuccess" + - $ref: "#/components/schemas/SuccessDescription" #################### # Shared parameters