From a686c0cc0276e1547029ca333e96707c28afbbf8 Mon Sep 17 00:00:00 2001 From: Lalit Date: Wed, 25 Jan 2023 12:59:51 +0530 Subject: [PATCH] docs: Add documentation for delete emoji endpoint. This endpoint was previously marked as `intentionally_undocumented` but that was mistake. Removed `intentionally_undocumented` and added proper documentation with valid `python_example` for this Endpoint. Fixes: #24084 --- api_docs/changelog.md | 5 ++++ api_docs/include/rest-endpoints.md | 1 + version.py | 2 +- zerver/openapi/openapi.py | 1 - zerver/openapi/python_examples.py | 12 +++++++++ zerver/openapi/zulip.yaml | 42 ++++++++++++++++++++++++++++++ zerver/tests/test_realm_emoji.py | 2 +- zerver/views/realm_emoji.py | 4 +-- zproject/urls.py | 3 +-- 9 files changed, 65 insertions(+), 7 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 464c51c9ee..cbac911dd3 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -20,6 +20,11 @@ format used by the Zulip server that they are interacting with. ## Changes in Zulip 8.0 +**Feature level 190** + +* [`DELETE /realm/emoji/{emoji_name}`](/api/deactivate-custom-emoji): This endpoint + now returns an HTTP status code of 404 when an emoji does not exist, instead of 400. + **Feature level 189** * [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults), diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md index 49a631dd0f..9e2b508eda 100644 --- a/api_docs/include/rest-endpoints.md +++ b/api_docs/include/rest-endpoints.md @@ -96,6 +96,7 @@ * [Remove a code playground](/api/remove-code-playground) * [Get all custom emoji](/api/get-custom-emoji) * [Upload custom emoji](/api/upload-custom-emoji) +* [Deactivate custom emoji](/api/deactivate-custom-emoji) * [Get all custom profile fields](/api/get-custom-profile-fields) * [Reorder custom profile fields](/api/reorder-custom-profile-fields) * [Create a custom profile field](/api/create-custom-profile-field) diff --git a/version.py b/version.py index 2fcb0db2d9..2c26e9f8c5 100644 --- a/version.py +++ b/version.py @@ -33,7 +33,7 @@ DESKTOP_WARNING_VERSION = "5.9.3" # Changes should be accompanied by documentation explaining what the # new level means in api_docs/changelog.md, as well as "**Changes**" # entries in the endpoint's documentation in `zulip.yaml`. -API_FEATURE_LEVEL = 189 +API_FEATURE_LEVEL = 190 # Bump the minor PROVISION_VERSION to indicate that folks should provision # only when going from an old version of the code to a newer version. Bump diff --git a/zerver/openapi/openapi.py b/zerver/openapi/openapi.py index 4ef4728992..36045e154a 100644 --- a/zerver/openapi/openapi.py +++ b/zerver/openapi/openapi.py @@ -23,7 +23,6 @@ OPENAPI_SPEC_PATH = os.path.abspath( # A list of endpoint-methods such that the endpoint # has documentation but not with this particular method. EXCLUDE_UNDOCUMENTED_ENDPOINTS = { - ("/realm/emoji/{emoji_name}", "delete"), ("/users", "patch"), } # Consists of endpoints with some documentation remaining. diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py index 70df59461c..48163b1b0c 100644 --- a/zerver/openapi/python_examples.py +++ b/zerver/openapi/python_examples.py @@ -1387,6 +1387,17 @@ def upload_custom_emoji(client: Client) -> None: validate_against_openapi_schema(result, "/realm/emoji/{emoji_name}", "post", "200") +@openapi_test_function("/realm/emoji/{emoji_name}:delete") +def delete_custom_emoji(client: Client) -> None: + # {code_example|start} + # Delete a custom emoji. + emoji_name = "my_custom_emoji" + result = client.call_endpoint(f"realm/emoji/{emoji_name}", method="DELETE") + # {code_example|end} + + validate_against_openapi_schema(result, "/realm/emoji/{emoji_name}", "delete", "200") + + @openapi_test_function("/users/me/alert_words:get") def get_alert_words(client: Client) -> None: # {code_example|start} @@ -1624,6 +1635,7 @@ def test_server_organizations(client: Client) -> None: remove_realm_playground(client) get_realm_emoji(client) upload_custom_emoji(client) + delete_custom_emoji(client) get_realm_profile_fields(client) reorder_realm_profile_fields(client) create_realm_profile_field(client) diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index ad548e5f91..50f27837a2 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -9174,6 +9174,48 @@ paths: responses: "200": $ref: "#/components/responses/SimpleSuccess" + delete: + operationId: deactivate-custom-emoji + summary: Deactivate custom emoji + tags: ["server_and_organizations"] + description: | + [Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from + the user's organization. + + Users can only deactivate custom emoji that they added themselves except for + organization administrators, who can deactivate any custom emoji. + + Note that deactivated emoji will still be visible in old messages, reactions, + user statuses and stream descriptions. + + **Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an + HTTP status code of 400 when the emoji did not exist, instead of 404. + parameters: + - name: emoji_name + required: true + in: path + description: | + The name of the custom emoji to deactivate. + schema: + type: string + example: green_tick + responses: + "200": + $ref: "#/components/responses/SimpleSuccess" + "404": + description: Not Found. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/JsonError" + - description: | + JSON response for when no emoji exists with the provided name. + example: + { + "result": "error", + "msg": "Emoji 'green_tick' does not exist", + } /realm/emoji: get: diff --git a/zerver/tests/test_realm_emoji.py b/zerver/tests/test_realm_emoji.py index 403dd22933..78fce0d44e 100644 --- a/zerver/tests/test_realm_emoji.py +++ b/zerver/tests/test_realm_emoji.py @@ -282,7 +282,7 @@ class RealmEmojiTest(ZulipTestCase): def test_delete_exception(self) -> None: self.login("iago") result = self.client_delete("/json/realm/emoji/invalid_emoji") - self.assert_json_error(result, "Emoji 'invalid_emoji' does not exist") + self.assert_json_error(result, "Emoji 'invalid_emoji' does not exist", status_code=404) def test_multiple_upload(self) -> None: self.login("iago") diff --git a/zerver/views/realm_emoji.py b/zerver/views/realm_emoji.py index b3d7607045..4d72a0d9f6 100644 --- a/zerver/views/realm_emoji.py +++ b/zerver/views/realm_emoji.py @@ -6,7 +6,7 @@ from django.utils.translation import gettext as _ from zerver.actions.realm_emoji import check_add_realm_emoji, do_remove_realm_emoji from zerver.decorator import require_member_or_admin from zerver.lib.emoji import check_remove_custom_emoji, check_valid_emoji_name, name_to_codepoint -from zerver.lib.exceptions import JsonableError +from zerver.lib.exceptions import JsonableError, ResourceNotFoundError from zerver.lib.request import REQ, has_request_variables from zerver.lib.response import json_success from zerver.models import RealmEmoji, UserProfile @@ -56,7 +56,7 @@ def delete_emoji(request: HttpRequest, user_profile: UserProfile, emoji_name: st if not RealmEmoji.objects.filter( realm=user_profile.realm, name=emoji_name, deactivated=False ).exists(): - raise JsonableError(_("Emoji '{}' does not exist").format(emoji_name)) + raise ResourceNotFoundError(_("Emoji '{}' does not exist").format(emoji_name)) check_remove_custom_emoji(user_profile, emoji_name) do_remove_realm_emoji(user_profile.realm, emoji_name, acting_user=user_profile) return json_success(request) diff --git a/zproject/urls.py b/zproject/urls.py index 7a0898ebc8..e5c75e0e86 100644 --- a/zproject/urls.py +++ b/zproject/urls.py @@ -265,9 +265,8 @@ v1_api_and_json_patterns = [ rest_path( "realm/emoji/", POST=upload_emoji, - DELETE=(delete_emoji, {"intentionally_undocumented"}), + DELETE=delete_emoji, ), - # this endpoint throws a status code 400 JsonableError when it should be a 404. # realm/icon -> zerver.views.realm_icon rest_path("realm/icon", POST=upload_icon, DELETE=delete_icon_backend, GET=get_icon_backend), # realm/logo -> zerver.views.realm_logo