api docs: Document POST /realm/profile_fields api endpoint.

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

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

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

@@ -58,6 +58,7 @@
 * [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)
+* [Create a custom profile field](/api/create-custom-profile-field)
 
 #### Real-time events
 

zerver/openapi/python_examples.py

@@ -303,6 +303,25 @@ def reorder_realm_profile_fields(client: Client) -> None:
     # {code_example|end}
     validate_against_openapi_schema(result, '/realm/profile_fields', 'patch', '200')
 
+@openapi_test_function("/realm/profile_fields:post")
+def create_realm_profile_field(client: Client) -> None:
+    # {code_example|start}
+    # Create a custom profile field in the user's organization.
+    request = {
+        'name': 'Phone',
+        'hint': 'Contact No.',
+        'field_type': 1
+    }
+
+    result = client.call_endpoint(
+        url='/realm/profile_fields',
+        method='POST',
+        request=request
+    )
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/realm/profile_fields', 'post', '200')
+
 @openapi_test_function("/realm/filters:post")
 def add_realm_filter(client: Client) -> None:
 
@@ -1264,6 +1283,7 @@ def test_server_organizations(client: Client) -> None:
     upload_custom_emoji(client)
     get_realm_profile_fields(client)
     reorder_realm_profile_fields(client)
+    create_realm_profile_field(client)
 
 def test_errors(client: Client) -> None:
     test_missing_request_argument(client)