api docs: Add documentation of deactivate-own-user endpoint.

Currently, there was no markdown page for deactivate-own-user API
endpoint. Created deactivate-own-user.md for the API page and
created a new owner client in test-api to reactivate the client
deactivated during testing.

Also changed endpoint name from deactivate-my-account to
deactivate-own-user, for better consistency with other endpoints.

Fixes #16163.

zerver/openapi/python_examples.py

@@ -392,6 +392,23 @@ def get_profile(client: Client) -> None:
     validate_against_openapi_schema(result, "/users/me", "get", "200")
 
 
+@openapi_test_function("/users/me:delete")
+def deactivate_own_user(client: Client, owner_client: Client) -> None:
+    user_id = client.get_profile()["user_id"]
+
+    # {code_example|start}
+    # Deactivate the account of the current user/bot that requests.
+    result = client.call_endpoint(
+        url="/users/me",
+        method="DELETE",
+    )
+    # {code_example|end}
+
+    # Reactivate the account to avoid polluting other tests.
+    owner_client.reactivate_user_by_id(user_id)
+    validate_against_openapi_schema(result, "/users/me", "delete", "200")
+
+
 @openapi_test_function("/get_stream_id:get")
 def get_stream_id(client: Client) -> int:
 
@@ -1295,7 +1312,7 @@ def test_messages(client: Client, nonadmin_client: Client) -> None:
     test_delete_message_edit_permission_error(client, nonadmin_client)
 
 
-def test_users(client: Client) -> None:
+def test_users(client: Client, owner_client: Client) -> None:
 
     create_user(client)
     get_members(client)
@@ -1320,6 +1337,7 @@ def test_users(client: Client) -> None:
     get_alert_words(client)
     add_alert_words(client)
     remove_alert_words(client)
+    deactivate_own_user(client, owner_client)
 
 
 def test_streams(client: Client, nonadmin_client: Client) -> None:
@@ -1371,10 +1389,10 @@ def test_errors(client: Client) -> None:
     test_invalid_stream_error(client)
 
 
-def test_the_api(client: Client, nonadmin_client: Client) -> None:
+def test_the_api(client: Client, nonadmin_client: Client, owner_client: Client) -> None:
 
     get_user_agent(client)
-    test_users(client)
+    test_users(client, owner_client)
     test_streams(client, nonadmin_client)
     test_messages(client, nonadmin_client)
     test_queues(client)

zerver/openapi/test_curl_examples.py

@@ -22,7 +22,7 @@ from zerver.openapi.curl_param_value_generators import (
 )
 
 
-def test_generated_curl_examples_for_success(client: Client) -> None:
+def test_generated_curl_examples_for_success(client: Client, owner_client: Client) -> None:
     authentication_line = f"{client.email}:{client.api_key}"
     # A limited Markdown engine that just processes the code example syntax.
     realm = get_realm("zulip")
@@ -49,11 +49,22 @@ def test_generated_curl_examples_for_success(client: Client) -> None:
                 curl_command_html = md_engine.convert(line.strip())
                 unescaped_html = html.unescape(curl_command_html)
                 curl_command_text = unescaped_html[len("<p><code>curl\n") : -len("</code></p>")]
-
                 curl_command_text = curl_command_text.replace(
                     "BOT_EMAIL_ADDRESS:BOT_API_KEY", authentication_line
                 )
 
+                # TODO: This needs_reactivation block is a hack.
+                # However, it's awkward to test the "deactivate
+                # myself" endpoint with how this system tries to use
+                # the same account for all tests without some special
+                # logic for that endpoint; and the hack is better than
+                # just not documenting the endpoint.
+                needs_reactivation = False
+                user_id = 0
+                if file_name == "templates/zerver/api/deactivate-own-user.md":
+                    needs_reactivation = True
+                    user_id = client.get_profile()["user_id"]
+
                 print("Testing {} ...".format(curl_command_text.split("\n")[0]))
 
                 # Turn the text into an arguments list.
@@ -69,6 +80,8 @@ def test_generated_curl_examples_for_success(client: Client) -> None:
                     )
                     response = json.loads(response_json)
                     assert response["result"] == "success"
+                    if needs_reactivation:
+                        owner_client.reactivate_user_by_id(user_id)
                 except (AssertionError, Exception):
                     error_template = """
 Error verifying the success of the API documentation curl example.

zerver/openapi/zulip.yaml

@@ -4552,10 +4552,15 @@ paths:
                           },
                       }
     delete:
-      operationId: deactivate_my_account
+      operationId: deactivate_own_user
       tags: ["users"]
       description: |
-        Delete the requesting user from the realm.
+        Deactivates the user's account.  See also the administrative endpoint for
+        [deactivating another user](/api/deactivate-user).
+
+        `DELETE {{ api_url }}/v1/users/me`
+
+        This endpoint is primarily useful to Zulip clients providing a user settings UI.
       responses:
         "200":
           description: Success.