api: Document /users/me/alert_words API endpoint.

templates/zerver/help/include/rest-endpoints.md

@@ -72,6 +72,9 @@
 * [Get subgroups of user group](/api/get-user-group-subgroups)
 * [Mute a user](/api/mute-user)
 * [Unmute a user](/api/unmute-user)
+* [Get all alert words](/api/get-alert-words)
+* [Add alert words](/api/add-alert-words)
+* [Remove alert words](/api/remove-alert-words)
 
 #### Server & organizations
 

zerver/openapi/python_examples.py

@@ -1379,25 +1379,40 @@ def upload_custom_emoji(client: Client) -> None:
 
 @openapi_test_function("/users/me/alert_words:get")
 def get_alert_words(client: Client) -> None:
+
+    # {code_example|start}
+    # Get all of the user's configured alert words.
     result = client.get_alert_words()
+    # {code_example|end}
+    validate_against_openapi_schema(result, "/users/me/alert_words", "get", "200")
 
     assert result["result"] == "success"
 
 
 @openapi_test_function("/users/me/alert_words:post")
 def add_alert_words(client: Client) -> None:
+
+    # {code_example|start}
+    # Add words (or phrases) to the user's set of configured alert words.
     word = ["foo", "bar"]
 
     result = client.add_alert_words(word)
+    # {code_example|end}
+    validate_against_openapi_schema(result, "/users/me/alert_words", "post", "200")
 
     assert result["result"] == "success"
 
 
 @openapi_test_function("/users/me/alert_words:delete")
 def remove_alert_words(client: Client) -> None:
+
+    # {code_example|start}
+    # Remove words (or phrases) from the user's set of configured alert words.
     word = ["foo"]
 
     result = client.remove_alert_words(word)
+    # {code_example|end}
+    validate_against_openapi_schema(result, "/users/me/alert_words", "delete", "200")
 
     assert result["result"] == "success"
 
@@ -1551,6 +1566,9 @@ def test_users(client: Client, owner_client: Client) -> None:
     deactivate_own_user(client, owner_client)
     add_user_mute(client)
     remove_user_mute(client)
+    get_alert_words(client)
+    add_alert_words(client)
+    remove_alert_words(client)
 
 
 def test_streams(client: Client, nonadmin_client: Client) -> None:

zerver/openapi/zulip.yaml

@@ -231,7 +231,8 @@ paths:
                                 alert_words:
                                   type: array
                                   description: |
-                                    Array of strings, each a configured alert word.
+                                    An array of strings, where each string is an alert word (or phrase)
+                                    configured by the user.
                                   items:
                                     type: string
                               additionalProperties: false
@@ -6934,6 +6935,159 @@ paths:
                     description: |
                       An example JSON error response when attempting to deactivate the only
                       organization owner in an organization:
+  /users/me/alert_words:
+    get:
+      operationId: get-alert-words
+      summary: Get all alert words
+      tags: ["users"]
+      description: |
+        Get all of the user's configured [alert words][alert-words].
+
+        [alert-words]: /help/pm-mention-alert-notifications#alert-words
+      responses:
+        "200":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - $ref: "#/components/schemas/SuccessDescription"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      alert_words:
+                        type: array
+                        description: |
+                          An array of strings, where each string is an alert word (or phrase)
+                          configured by the user.
+                        items:
+                          type: string
+                    example:
+                      {
+                        "result": "success",
+                        "msg": "",
+                        "alert_words": ["natural", "illustrious"],
+                      }
+    post:
+      operationId: add-alert-words
+      summary: Add alert words
+      tags: ["users"]
+      description: |
+        Add words (or phrases) to the user's set of configured [alert words][alert-words].
+
+        [alert-words]: /help/pm-mention-alert-notifications#alert-words
+      parameters:
+        - name: alert_words
+          in: query
+          description: |
+            An array of strings to be added to the user's set of configured
+            alert words. Strings already present in the user's set of alert words
+            already are ignored.
+
+            Alert words are case insensitive.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+              example: ["foo", "bar"]
+          required: true
+      responses:
+        "200":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - $ref: "#/components/schemas/SuccessDescription"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      alert_words:
+                        type: array
+                        description: |
+                          An array of strings, where each string is an alert word (or phrase)
+                          configured by the user.
+                        items:
+                          type: string
+                    example:
+                      {
+                        "result": "success",
+                        "msg": "",
+                        "alert_words": ["foo", "bar", "natural", "illustrious"],
+                      }
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/CodedError"
+                  - example:
+                      {
+                        "code": "BAD_REQUEST",
+                        "msg": "alert_words[0] is too long (limit: 100 characters)",
+                        "result": "error",
+                      }
+                    description: |
+                      An example JSON response for when a supplied alert word (or phrase)
+                      exceeds the character limit:
+    delete:
+      operationId: remove-alert-words
+      summary: Remove alert words
+      tags: ["users"]
+      description: |
+        Remove words (or phrases) from the user's set of configured [alert words][alert-words].
+
+        Alert words are case insensitive.
+
+        [alert-words]: /help/pm-mention-alert-notifications#alert-words
+      parameters:
+        - name: alert_words
+          in: query
+          description: |
+            An array of strings to be removed from the user's set of configured
+            alert words. Strings that are not in the user's set of alert words
+            are ignored.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+              example: ["foo"]
+          required: true
+      responses:
+        "200":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - $ref: "#/components/schemas/SuccessDescription"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      alert_words:
+                        type: array
+                        description: |
+                          An array of strings, where each string is an alert word (or phrase)
+                          configured by the user.
+                        items:
+                          type: string
+                    example:
+                      {
+                        "result": "success",
+                        "msg": "",
+                        "alert_words": ["bar", "natural", "illustrious"],
+                      }
   /users/me/status:
     post:
       operationId: update-status

zerver/tests/test_openapi.py

@@ -206,7 +206,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
     pending_endpoints = {
         #### TODO: These endpoints are a priority to document:
         "/users/me/presence",
-        "/users/me/alert_words",
         # These are a priority to document but don't match our normal URL schemes
         # and thus may be complicated to document with our current tooling.
         # (No /api/v1/ or /json prefix).