openapi: Document android_gcm_reg_id endpoints.

This commit adds API documentation for "/users/me/android_gcm_reg_id:post"
and "/users/me/android_gcm_reg_id:delete" endpoints.

Co-authored-by: Suyash Vardhan Mathur <suyash.mathur@research.iiit.ac.in>

api_docs/include/rest-endpoints.md

@@ -127,3 +127,5 @@
 * [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)
+* [Add an FCM registration token](/api/add-fcm-token)
+* [Remove an FCM registration token](/api/remove-fcm-token)

zerver/openapi/python_examples.py

@@ -1391,6 +1391,30 @@ def remove_apns_token(client: Client) -> None:
     validate_against_openapi_schema(result, "/users/me/apns_device_token", "delete", "200")
 
 
+@openapi_test_function("/users/me/android_gcm_reg_id:post")
+def add_fcm_token(client: Client) -> None:
+    # {code_example|start}
+    request = {"token": "android-token"}
+    result = client.call_endpoint(
+        url="/users/me/android_gcm_reg_id", method="POST", request=request
+    )
+    # {code_example|end}
+    validate_against_openapi_schema(result, "/users/me/android_gcm_reg_id", "post", "200")
+
+
+@openapi_test_function("/users/me/android_gcm_reg_id:delete")
+def remove_fcm_token(client: Client) -> None:
+    # {code_example|start}
+    request = {
+        "token": "android-token",
+    }
+    result = client.call_endpoint(
+        url="/users/me/android_gcm_reg_id", method="DELETE", request=request
+    )
+    # {code_example|end}
+    validate_against_openapi_schema(result, "/users/me/android_gcm_reg_id", "delete", "200")
+
+
 @openapi_test_function("/typing:post")
 def set_typing_status(client: Client) -> None:
     ensure_users([10, 11], ["hamlet", "iago"])
@@ -1682,6 +1706,8 @@ def test_users(client: Client, owner_client: Client) -> None:
     remove_alert_words(client)
     add_apns_token(client)
     remove_apns_token(client)
+    add_fcm_token(client)
+    remove_fcm_token(client)
 
 
 def test_streams(client: Client, nonadmin_client: Client) -> None:

zerver/openapi/zulip.yaml

@@ -10151,6 +10151,96 @@ paths:
                           }
                         description: |
                           A typical failed JSON response for when the token does not exist:
+  /users/me/android_gcm_reg_id:
+    post:
+      operationId: add-fcm-token
+      summary: Add an FCM registration token
+      tags: ["users"]
+      description: |
+        This endpoint adds an FCM registration token for 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: android-token
+              required:
+                - token
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/CodedError"
+                  - description: |
+                      A typical failed JSON response for when the token's length is invalid
+                      or is empty:
+                    example:
+                      {
+                        "result": "error",
+                        "msg": "Empty or invalid length token",
+                        "code": "BAD_REQUEST",
+                      }
+    delete:
+      operationId: remove-fcm-token
+      summary: Remove an FCM registration token
+      tags: ["users"]
+      description: |
+        This endpoint removes an FCM registration token for 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: android-token
+              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 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

zerver/tests/test_openapi.py

@@ -248,8 +248,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         #### Mobile-app only endpoints; important for mobile developers.
         # Mobile interface for development environment login
         "/dev_list_users",
-        # Registration for iOS/Android mobile push notifications.
-        "/users/me/android_gcm_reg_id",
         #### These personal settings endpoints have modest value to document:
         "/users/me/avatar",
         "/users/me/api_key/regenerate",