From b047bf0d7966156d05c4cded593bb34d95ba1cc1 Mon Sep 17 00:00:00 2001 From: Vector73 Date: Fri, 10 May 2024 09:56:36 +0530 Subject: [PATCH] openapi: Document apns_device_token endpoints. This commit adds API documentation for "/users/me/apns_device_token:post" and "/users/me/apns_device_token:delete" endpoints. openapi: Document android_gcm_reg_id endpoints. Co-authored-by: Suyash Vardhan Mathur --- api_docs/changelog.md | 2 +- api_docs/include/rest-endpoints.md | 2 + zerver/openapi/python_examples.py | 26 +++++++ zerver/openapi/zulip.yaml | 111 +++++++++++++++++++++++++++++ zerver/tests/test_openapi.py | 1 - 5 files changed, 140 insertions(+), 2 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 17a8c29ff8..595425f51c 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -339,7 +339,7 @@ No changes; feature level used for Zulip 8.0 release. **Feature level 223** -* `POST /users/me/apns_device_token`: +* [`POST /users/me/apns_device_token`](/api/add-apns-token): The `appid` parameter is now required. Previously it defaulted to the server setting `ZULIP_IOS_APP_ID`, defaulting to "org.zulip.Zulip". diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md index 07eef381dd..a30a9fd121 100644 --- a/api_docs/include/rest-endpoints.md +++ b/api_docs/include/rest-endpoints.md @@ -125,3 +125,5 @@ * [Fetch an API key (production)](/api/fetch-api-key) * [Fetch an API key (development only)](/api/dev-fetch-api-key) * [Send a test notification to mobile device(s)](/api/test-notify) +* [Add an APNs device token](/api/add-apns-token) +* [Remove an APNs device token](/api/remove-apns-token) diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py index 1ac3a2817c..c2bfcdaf29 100644 --- a/zerver/openapi/python_examples.py +++ b/zerver/openapi/python_examples.py @@ -1367,6 +1367,30 @@ def get_stream_topics(client: Client, stream_id: int) -> None: validate_against_openapi_schema(result, "/users/me/{stream_id}/topics", "get", "200") +@openapi_test_function("/users/me/apns_device_token:post") +def add_apns_token(client: Client) -> None: + # {code_example|start} + request = {"token": "apple-tokenbb", "appid": "org.zulip.Zulip"} + result = client.call_endpoint(url="/users/me/apns_device_token", method="POST", request=request) + # {code_example|end} + + validate_against_openapi_schema(result, "/users/me/apns_device_token", "post", "200") + + +@openapi_test_function("/users/me/apns_device_token:delete") +def remove_apns_token(client: Client) -> None: + # {code_example|start} + request = { + "token": "apple-tokenbb", + } + result = client.call_endpoint( + url="/users/me/apns_device_token", method="DELETE", request=request + ) + # {code_example|end} + + validate_against_openapi_schema(result, "/users/me/apns_device_token", "delete", "200") + + @openapi_test_function("/typing:post") def set_typing_status(client: Client) -> None: ensure_users([10, 11], ["hamlet", "iago"]) @@ -1656,6 +1680,8 @@ def test_users(client: Client, owner_client: Client) -> None: get_alert_words(client) add_alert_words(client) remove_alert_words(client) + add_apns_token(client) + remove_apns_token(client) def test_streams(client: Client, nonadmin_client: Client) -> None: diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 17740e9853..c0d6ec0df0 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -10039,7 +10039,118 @@ paths: } description: | An example JSON response for when the user is not previously muted: + /users/me/apns_device_token: + post: + operationId: add-apns-token + summary: Add an APNs device token + tags: ["users"] + description: | + This endpoint adds an APNs device token to register for iOS push notifications. + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + token: + description: | + The token provided by the device. + type: string + example: apple-tokenbb + appid: + description: | + The ID of the Zulip app that is making the request. + **Changes**: In Zulip 8.0 (feature level 223), this parameter was made + required. Previously, if it was unspecified, the server would use a default + value (based on the `ZULIP_IOS_APP_ID` server setting, which + defaulted to `"org.zulip.Zulip"`). + type: string + example: org.zulip.Zulip + required: + - token + - appid + responses: + "200": + $ref: "#/components/responses/SimpleSuccess" + "400": + description: Bad request. + content: + application/json: + schema: + oneOf: + - allOf: + - $ref: "#/components/schemas/CodedError" + - description: | + A typical failed JSON response for when the token's length is invalid + or it is empty: + example: + { + "result": "error", + "msg": "Empty or invalid length token", + "code": "BAD_REQUEST", + } + - allOf: + - $ref: "#/components/schemas/CodedError" + - example: + { + "result": "error", + "msg": "Invalid APNS token", + "code": "BAD_REQUEST", + } + description: | + A typical failed JSON response for when the APNs token is invalid: + delete: + operationId: remove-apns-token + summary: Remove an APNs device token + tags: ["users"] + description: | + This endpoint removes an APNs device token for iOS push notifications. + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + token: + description: | + The token provided by the device. + type: string + example: apple-tokenbb + required: + - token + responses: + "200": + $ref: "#/components/responses/SimpleSuccess" + "400": + description: Bad request. + content: + application/json: + schema: + oneOf: + - allOf: + - $ref: "#/components/schemas/CodedError" + - description: | + A typical failed JSON response for when the token's length is invalid + or it is empty: + example: + { + "result": "error", + "msg": "Empty or invalid length token", + "code": "BAD_REQUEST", + } + - allOf: + - $ref: "#/components/schemas/CodedError" + - example: + { + "result": "error", + "msg": "Token does not exist", + "code": "BAD_REQUEST", + } + description: | + A typical failed JSON response for when the token does not exist: /users/{user_id}/subscriptions/{stream_id}: get: operationId: get-subscription-status diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py index 0591164294..d13295a74c 100644 --- a/zerver/tests/test_openapi.py +++ b/zerver/tests/test_openapi.py @@ -250,7 +250,6 @@ class OpenAPIArgumentsTest(ZulipTestCase): "/dev_list_users", # Registration for iOS/Android mobile push notifications. "/users/me/android_gcm_reg_id", - "/users/me/apns_device_token", #### These personal settings endpoints have modest value to document: "/users/me/avatar", "/users/me/api_key/regenerate",