api docs: Document PATCH /realm/profile_fields endpoint.

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

@@ -0,0 +1,33 @@
+# Reorder custom profile fields
+
+{generate_api_description(/realm/profile_fields:patch)}
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/realm/profile_fields:patch|example(admin_config=True)}
+
+{tab|curl}
+
+{generate_code_example(curl)|/realm/profile_fields:patch|example}
+
+{end_tabs}
+
+## Parameters
+
+{generate_api_arguments_table|zulip.yaml|/realm/profile_fields:patch}
+
+## Response
+
+#### Return values
+
+{generate_return_values_table|zulip.yaml|/realm/profile_fields:patch}
+
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/realm/profile_fields:patch|fixture(200)}

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

@@ -57,6 +57,7 @@
 * [Get all custom emoji](/api/get-custom-emoji)
 * [Upload custom emoji](/api/upload-custom-emoji)
 * [Get all custom profile fields](/api/get-custom-profile-fields)
+* [Reorder custom profile fields](/api/reorder-custom-profile-fields)
 
 #### Real-time events
 

zerver/openapi/python_examples.py

@@ -286,6 +286,23 @@ def get_realm_profile_fields(client: Client) -> None:
     # {code_example|end}
     validate_against_openapi_schema(result, '/realm/profile_fields', 'get', '200')
 
+@openapi_test_function("/realm/profile_fields:patch")
+def reorder_realm_profile_fields(client: Client) -> None:
+    # {code_example|start}
+    # Reorder the custom profile fields in the user's organization.
+    order = [8, 7, 6, 5, 4, 3, 2, 1]
+    request = {
+        'order': json.dumps(order)
+    }
+
+    result = client.call_endpoint(
+        url='/realm/profile_fields',
+        method='PATCH',
+        request=request
+    )
+    # {code_example|end}
+    validate_against_openapi_schema(result, '/realm/profile_fields', 'patch', '200')
+
 @openapi_test_function("/realm/filters:post")
 def add_realm_filter(client: Client) -> None:
 
@@ -1246,6 +1263,7 @@ def test_server_organizations(client: Client) -> None:
     get_realm_emoji(client)
     upload_custom_emoji(client)
     get_realm_profile_fields(client)
+    reorder_realm_profile_fields(client)
 
 def test_errors(client: Client) -> None:
     test_missing_request_argument(client)