Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api_docs: Revise emoji documentation for statuses and reactions. 

Adds and updates changelog documentation for
`POST /users/me/status` feature level 86 addition
of new emoji parameters.

Makes description text for emoji `reaction_type` consistent
throughout API documentation and also adds better description
of the `unicode_emoji` namespace.

Redirects emoji field links in `user_status` event to go to
the parameters in `/update-status` endpoint, which was not a
documented endpoint when the event documentation was created.
This commit is contained in:
Lauryn Menard 2022-04-11 21:35:54 +02:00 committed by Tim Abbott
parent 1151118cc8
commit 3f9ccf3225
2 changed files with 85 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
templates/zerver/api/changelog.md
View File

@ -333,8 +333,8 @@ No changes; feature level used for Zulip 5.0 release.
`emoji_code`, and `reaction_type` fields to `user_status` objects. `emoji_code`, and `reaction_type` fields to `user_status` objects.
* [`POST /register`](/api/register-queue): Added `emoji_name`, * [`POST /register`](/api/register-queue): Added `emoji_name`,
`emoji_code`, and `reaction_type` fields to `user_status` objects. `emoji_code`, and `reaction_type` fields to `user_status` objects.
* `POST /users/me/status`: Added support for new `emoji_name`, * [`POST /users/me/status`](/api/update-status): Added support for new
`emoji_code`, and `reaction_type` parameters. `emoji_name`, `emoji_code`, and `reaction_type` parameters.
**Feature level 85** **Feature level 85**

131
zerver/openapi/zulip.yaml
View File

@ -1513,36 +1513,39 @@ paths:
type: string type: string
description: | description: |
The text content of the status message. The text content of the status message.
This will be `""` for users who set a status without selecting
or writing a message.
emoji_name: emoji_name:
type: string type: string
description: | description: |
The [emoji name](/api/add-reaction#parameters) for the emoji The [emoji name](/api/update-status#parameter-emoji_name) for
the user selected for their new status. the emoji the user selected for their new status.
This will be "" for users who set a status without selecting This will be `""` for users who set a status without selecting
an emoji. an emoji.
**Changes**; New in Zulip 5.0 (feature level 86). **Changes**: New in Zulip 5.0 (feature level 86).
emoji_code: emoji_code:
type: string type: string
description: | description: |
The [emoji code](/api/add-reaction#parameters) for the emoji The [emoji code](/api/update-status#parameter-emoji_code) for
the user selected for their new status. the emoji the user selected for their new status.
This will be "" for users who set a status without selecting This will be `""` for users who set a status without selecting
an emoji. an emoji.
**Changes**; New in Zulip 5.0 (feature level 86). **Changes**: New in Zulip 5.0 (feature level 86).
reaction_type: reaction_type:
type: string type: string
description: | description: |
The [emoji type](/api/add-reaction#parameters) for the emoji The [emoji type](/api/update-status#parameter-reaction_type) for
the user selected for their new status. the emoji the user selected for their new status.
This will be "" for users who set a status without selecting This will be `""` for users who set a status without selecting
an emoji. an emoji.
**Changes**; New in Zulip 5.0 (feature level 86). **Changes**: New in Zulip 5.0 (feature level 86).
user_id: user_id:
type: integer type: integer
description: | description: |
@ -5467,7 +5470,6 @@ paths:
responses: responses:
"200": "200":
$ref: "#/components/responses/SimpleSuccess" $ref: "#/components/responses/SimpleSuccess"
"400": "400":
description: Bad request. description: Bad request.
content: content:
@ -6635,6 +6637,9 @@ paths:
Clients that wish to set the user's status to a specific value should Clients that wish to set the user's status to a specific value should
pass all supported parameters. pass all supported parameters.
**Changes**: In Zulip 5.0 (feature level 86), added support for
`emoji_name`, `emoji_code`, and `reaction_type` parameters.
parameters: parameters:
- name: status_text - name: status_text
schema: schema:
@ -6663,6 +6668,8 @@ paths:
in: query in: query
description: | description: |
The name for the emoji to associate with this status. The name for the emoji to associate with this status.
**Changes**: New in Zulip 5.0 (feature level 86).
example: car example: car
required: false required: false
- name: emoji_code - name: emoji_code
@ -6673,8 +6680,7 @@ paths:
A unique identifier, defining the specific emoji codepoint requested, A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`. within the namespace of the `reaction_type`.
For example, for `unicode_emoji`, this will be an encoding of the **Changes**: New in Zulip 5.0 (feature level 86).
Unicode codepoint; for `realm_emoji`, it'll be the ID of the realm emoji.
example: 1f697 example: 1f697
required: false required: false
- name: reaction_type - name: reaction_type
@ -6682,14 +6688,23 @@ paths:
type: string type: string
in: query in: query
description: | description: |
One of the following values: A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
- `unicode_emoji`: Unicode emoji (`emoji_code` will be its Unicode Must be one of the following values:
codepoint).
- `realm_emoji`: [Custom emoji](/help/custom-emoji). - `unicode_emoji` : In this namespace, `emoji_code` will be a
(`emoji_code` will be its ID). dash-separated hex encoding of the sequence of Unicode codepoints
- `zulip_extra_emoji`: Special emoji included with Zulip. Exists to that define this emoji in the Unicode specification.
namespace the `zulip` emoji.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: New in Zulip 5.0 (feature level 86).
example: unicode_emoji example: unicode_emoji
required: false required: false
responses: responses:
@ -9799,14 +9814,21 @@ paths:
reaction_type: reaction_type:
type: string type: string
description: | description: |
If present, one of the following values: If present, a string indicating the type of emoji. Each emoji
`reaction_type` has an independent namespace for values of `emoji_code`.
- `unicode_emoji`: Unicode emoji (`emoji_code` will be its Unicode Must be one of the following values:
codepoint).
- `realm_emoji`: [Custom emoji](/help/custom-emoji). - `unicode_emoji` : In this namespace, `emoji_code` will be a
(`emoji_code` will be its ID). dash-separated hex encoding of the sequence of Unicode codepoints
- `zulip_extra_emoji`: Special emoji included with Zulip. Exists to that define this emoji in the Unicode specification.
namespace the `zulip` emoji.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: New in Zulip 5.0 (feature level 86). **Changes**: New in Zulip 5.0 (feature level 86).
user_settings: user_settings:
@ -14847,29 +14869,33 @@ components:
EmojiBase: EmojiBase:
type: object type: object
properties: properties:
emoji_name:
type: string
description: |
Name of the emoji.
emoji_code: emoji_code:
type: string type: string
description: | description: |
A unique identifier, defining the specific emoji codepoint requested, A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`. within the namespace of the `reaction_type`.
For example, for `unicode_emoji`, this will be an encoding of the
Unicode codepoint; for `realm_emoji`, it'll be the ID of the realm emoji.
emoji_name:
type: string
description: |
Name of the emoji.
reaction_type: reaction_type:
type: string type: string
description: | description: |
One of the following values: A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
- `unicode_emoji`: Unicode emoji (`emoji_code` will be its Unicode Must be one of the following values:
codepoint).
- `realm_emoji`: [Custom emoji](/help/custom-emoji). - `unicode_emoji` : In this namespace, `emoji_code` will be a
(`emoji_code` will be its ID). dash-separated hex encoding of the sequence of Unicode codepoints
- `zulip_extra_emoji`: Special emoji included with Zulip. Exists to that define this emoji in the Unicode specification.
namespace the `zulip` emoji.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
EmojiReactionBase: EmojiReactionBase:
allOf: allOf:
- $ref: "#/components/schemas/EmojiBase" - $ref: "#/components/schemas/EmojiBase"
@ -16006,14 +16032,23 @@ components:
name: reaction_type name: reaction_type
in: query in: query
description: | description: |
If an app is adding/removing a vote on an existing reaction, A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
If an API client is adding/removing a vote on an existing reaction,
it should pass this parameter using the value the server provided it should pass this parameter using the value the server provided
for the existing reaction for specificity. Supported values: for the existing reaction for specificity. Supported values:
- `unicode_emoji`: Unicode emoji (`emoji_code` will be its Unicode codepoint). - `unicode_emoji` : In this namespace, `emoji_code` will be a
- `realm_emoji`: Custom emoji. (`emoji_code` will be its ID). dash-separated hex encoding of the sequence of Unicode codepoints
- `zulip_extra_emoji`: Special emoji included with Zulip. Exists to that define this emoji in the Unicode specification.
namespace the `zulip` emoji.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: In Zulip 3.0 (feature level 2), this become **Changes**: In Zulip 3.0 (feature level 2), this become
optional for [custom emoji](/help/custom-emoji); optional for [custom emoji](/help/custom-emoji);