apidocs: Migrate admin_config out of templates.

Currently, the `admin_config` configuration was
hardcoded in the templates, but as a goal of creating
a common template, we need to move all configurations
outside.

Moved the checking for function and language which need
admin_config out of templates into the code and added a
boolean `x-admin-config` to store whehter the operation
requires admin config.

Also, added the banner for admin access to auto-generate
if admin_config is present, and fixed the admin_config
for endpoints that were earlier missing it in the templates.

templates/zerver/api/create-custom-profile-field.md

@@ -7,7 +7,7 @@
 {start_tabs}
 {tab|python}
 
-{generate_code_example(python)|/realm/profile_fields:post|example(admin_config=True)}
+{generate_code_example(python)|/realm/profile_fields:post|example}
 
 {generate_code_example(javascript)|/realm/profile_fields:post|example}
 

templates/zerver/api/create-user.md

@@ -7,9 +7,9 @@
 {start_tabs}
 {tab|python}
 
-{generate_code_example(python)|/users:post|example(admin_config=True)}
+{generate_code_example(python)|/users:post|example}
 
-{generate_code_example(javascript)|/users:post|example(admin_config=True)}
+{generate_code_example(javascript)|/users:post|example}
 
 {tab|curl}
 

templates/zerver/api/delete-message.md

@@ -9,7 +9,7 @@
 {start_tabs}
 {tab|python}
 
-{generate_code_example(python)|/messages/{message_id}:delete|example(admin_config=True)}
+{generate_code_example(python)|/messages/{message_id}:delete|example}
 
 {generate_code_example(javascript)|/messages/{message_id}:delete|example}
 

templates/zerver/api/reorder-custom-profile-fields.md

@@ -7,7 +7,7 @@
 {start_tabs}
 {tab|python}
 
-{generate_code_example(python)|/realm/profile_fields:patch|example(admin_config=True)}
+{generate_code_example(python)|/realm/profile_fields:patch|example}
 
 {generate_code_example(javascript)|/realm/profile_fields:patch|example}
 

zerver/openapi/markdown_extension.py

@@ -19,6 +19,7 @@ from markdown.preprocessors import Preprocessor
 
 import zerver.openapi.python_examples
 from zerver.openapi.openapi import (
+    check_requires_administrator,
     generate_openapi_fixture,
     get_openapi_description,
     get_openapi_summary,
@@ -76,6 +77,7 @@ DEFAULT_EXAMPLE = {
     "string": "demo",
     "boolean": False,
 }
+ADMIN_CONFIG_LANGUAGES = ["python", "javascript"]
 
 
 def parse_language_and_options(input_str: Optional[str]) -> Tuple[str, Dict[str, Any]]:
@@ -426,7 +428,10 @@ class APICodeExamplesPreprocessor(Preprocessor):
                         if argument:
                             text = self.render_fixture(function, name=argument)
                     elif key == "example":
-                        if argument == "admin_config=True":
+                        path, method = function.rsplit(":", 1)
+                        if language in ADMIN_CONFIG_LANGUAGES and check_requires_administrator(
+                            path, method
+                        ):
                             text = SUPPORTED_LANGUAGES[language]["render"](
                                 function, admin_config=True
                             )
@@ -525,6 +530,8 @@ class APITitlePreprocessor(Preprocessor):
         raw_title = get_openapi_summary(path, method)
         title.extend(raw_title.splitlines())
         title = ["# " + line for line in title]
+        if check_requires_administrator(path, method):
+            title.append("{!api-admin-only.md!}")
         return title
 
 

zerver/openapi/openapi.py

@@ -214,6 +214,13 @@ def get_openapi_fixture_description(endpoint: str, method: str, status_code: str
     return get_schema(endpoint, method, status_code)["description"]
 
 
+def check_requires_administrator(endpoint: str, method: str) -> bool:
+    """Fetch if the endpoint requires admin config."""
+    return openapi_spec.openapi()["paths"][endpoint][method.lower()].get(
+        "x-requires-administrator", False
+    )
+
+
 def generate_openapi_fixture(endpoint: str, method: str, status_code: str = "200") -> List[str]:
     """Generate fixture to be rendered"""
     fixture = []

zerver/openapi/zulip.yaml

@@ -5007,6 +5007,7 @@ paths:
         This API corresponds to the
         [delete a message completely][delete-completely] feature documented in
         the Zulip Help Center.
+      x-requires-administrator: true
       parameters:
         - $ref: "#/components/parameters/MessageId"
       responses:
@@ -5264,6 +5265,7 @@ paths:
         Create a new user account via the API.
 
         `POST {{ api_url }}/v1/users`
+      x-requires-administrator: true
       parameters:
         - name: email
           in: query
@@ -5329,9 +5331,8 @@ paths:
       operationId: reactivate_user
       summary: Reactivate a user
       tags: ["users"]
+      x-requires-administrator: true
       description: |
-        {!api-admin-only.md!}
-
         [Reactivates a
         user](https://zulip.com/help/deactivate-or-reactivate-a-user)
         given their user ID.
@@ -6531,8 +6532,6 @@ paths:
       summary: Reorder custom profile fields
       tags: ["server_and_organizations"]
       description: |
-        {!api-admin-only.md!}
-
         Reorder the custom profile fields in the user's organization.
 
         `PATCH {{ api_url }}/v1/realm/profile_fields`
@@ -6542,6 +6541,7 @@ paths:
 
         This endpoint is used to implement the dragging feature described in the
         [custom profile fields documentation](/help/add-custom-profile-fields).
+      x-requires-administrator: true
       parameters:
         - name: order
           in: query
@@ -6570,11 +6570,10 @@ paths:
       summary: Create a custom profile field
       tags: ["server_and_organizations"]
       description: |
-        {!api-admin-only.md!}
-
         [Create a custom profile field](/help/add-custom-profile-fields) in the user's organization.
 
         `POST {{ api_url }}/v1/realm/profile_fields`
+      x-requires-administrator: true
       parameters:
         - name: name
           in: query
@@ -6960,9 +6959,8 @@ paths:
       operationId: update_user
       summary: Update a user
       tags: ["users"]
+      x-requires-administrator: true
       description: |
-        {!api-admin-only.md!}
-
         Administrative endpoint to update the details of another user in the organization.
 
         `PATCH {{ api_url }}/v1/users/{user_id}`
@@ -7042,9 +7040,8 @@ paths:
       operationId: deactivate_user
       summary: Deactivate a user
       tags: ["users"]
+      x-requires-administrator: true
       description: |
-        {!api-admin-only.md!}
-
         [Deactivates a
         user](https://zulip.com/help/deactivate-or-reactivate-a-user)
         given their user ID.