Zulip server and web application. Open-source team chat that helps teams stay productive and focused.
api-docs: Document PATCH and DELETE /realm/profile_fields/{field_id}.
Agnish Bauria02fd83cdeee
diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.mdindex 1cc0b46462c..1efa056d238 100644--- a/api_docs/include/rest-endpoints.md+++ b/api_docs/include/rest-endpoints.md@@ -151,6 +151,8 @@* [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)+* [Update a custom profile field](/api/update-custom-profile-field)+* [Delete a custom profile field](/api/delete-custom-profile-field)* [Update realm-level defaults of user settings](/api/update-realm-user-settings-defaults)* [Get allowed domains](/api/get-realm-domains)* [Add an allowed domain](/api/add-realm-domain)diff --git a/zerver/openapi/curl_param_value_generators.py b/zerver/openapi/curl_param_value_generators.pyindex 133aa806a82..64cc647cab0 100644--- a/zerver/openapi/curl_param_value_generators.py+++ b/zerver/openapi/curl_param_value_generators.py@@ -14,6 +14,7 @@ from django.utils.timezone import now as timezone_nowfrom zerver.actions.channel_folders import check_add_channel_folderfrom zerver.actions.create_user import do_create_user+from zerver.actions.custom_profile_fields import try_add_realm_custom_profile_fieldfrom zerver.actions.presence import update_user_presencefrom zerver.actions.reactions import do_add_reactionfrom zerver.actions.realm_domains import do_add_realm_domain@@ -24,8 +25,9 @@ from zerver.lib.events import do_events_registerfrom zerver.lib.initial_password import initial_passwordfrom zerver.lib.test_classes import ZulipTestCasefrom zerver.lib.test_helpers import read_test_image_file+from zerver.lib.types import ProfileFieldDatafrom zerver.lib.upload import upload_message_attachment-from zerver.models import Client, Message, NamedUserGroup, UserPresence+from zerver.models import Client, CustomProfileField, Message, NamedUserGroup, UserPresencefrom zerver.models.channel_folders import ChannelFolderfrom zerver.models.realms import RealmExport, get_realmfrom zerver.models.users import UserProfile, get_user@@ -359,6 +361,36 @@ def remove_realm_playground() -> dict[str, object]:}+@openapi_param_value_generator(["/realm/profile_fields/{field_id}:patch"])+def update_custom_profile_field() -> dict[str, object]:+ # A dropdown field, so that the documented field_data example validates.+ field_data: ProfileFieldData = {+ "0": {"text": "Vim", "order": "1"},+ "1": {"text": "Emacs", "order": "2"},+ }+ field = try_add_realm_custom_profile_field(+ get_realm("zulip"),+ "Favorite IDE",+ CustomProfileField.DROPDOWN,+ field_data=field_data,+ )+ return {+ "field_id": field.id,+ }+++@openapi_param_value_generator(["/realm/profile_fields/{field_id}:delete"])+def delete_custom_profile_field() -> dict[str, object]:+ field = try_add_realm_custom_profile_field(+ get_realm("zulip"),+ "Field to delete",+ CustomProfileField.SHORT_TEXT,+ )+ return {+ "field_id": field.id,+ }++@openapi_param_value_generator(["/users/{user_id}:delete"])def deactivate_user() -> dict[str, object]:user_profile = do_create_user(diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.pyindex 985e62e12be..1daa5a43374 100644--- a/zerver/openapi/python_examples.py+++ b/zerver/openapi/python_examples.py@@ -661,7 +661,7 @@ def reorder_realm_profile_fields(client: Client) -> None:@openapi_test_function("/realm/profile_fields:post")-def create_realm_profile_field(client: Client) -> None:+def create_realm_profile_field(client: Client) -> int:# {code_example|start}# Create a custom profile field in the user's organization.request = {"name": "Phone", "hint": "Contact no.", "field_type": 1}@@ -669,6 +669,30 @@ def create_realm_profile_field(client: Client) -> None:# {code_example|end}assert_success_response(result)validate_against_openapi_schema(result, "/realm/profile_fields", "post", "200")+ return result["id"]+++@openapi_test_function("/realm/profile_fields/{field_id}:patch")+def update_realm_profile_field(client: Client, field_id: int) -> None:+ # {code_example|start}+ # Update a custom profile field in the user's organization.+ request = {"name": "Cell", "hint": "Contact number."}+ result = client.call_endpoint(+ url=f"/realm/profile_fields/{field_id}", method="PATCH", request=request+ )+ # {code_example|end}+ assert_success_response(result)+ validate_against_openapi_schema(result, "/realm/profile_fields/{field_id}", "patch", "200")+++@openapi_test_function("/realm/profile_fields/{field_id}:delete")+def delete_realm_profile_field(client: Client, field_id: int) -> None:+ # {code_example|start}+ # Delete a custom profile field in the user's organization.+ result = client.call_endpoint(url=f"/realm/profile_fields/{field_id}", method="DELETE")+ # {code_example|end}+ assert_success_response(result)+ validate_against_openapi_schema(result, "/realm/profile_fields/{field_id}", "delete", "200")@openapi_test_function("/realm/filters:post")@@ -2299,7 +2323,9 @@ def test_server_organizations(client: Client) -> None:delete_custom_emoji(client)get_realm_profile_fields(client)reorder_realm_profile_fields(client)- create_realm_profile_field(client)+ profile_field_id = create_realm_profile_field(client)+ update_realm_profile_field(client, profile_field_id)+ delete_realm_profile_field(client, profile_field_id)export_id = export_realm(client)get_realm_exports(client)get_realm_export_consents(client)diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yamlindex cfd1573fc90..2dc6999d49d 100644--- a/zerver/openapi/zulip.yaml+++ b/zerver/openapi/zulip.yaml@@ -15454,6 +15454,164 @@ paths:description: |The ID for the custom profile field.example: {"result": "success", "msg": "", "id": 9}+ /realm/profile_fields/{field_id}:+ patch:+ operationId: update-custom-profile-field+ summary: Update a custom profile field+ tags: ["server_and_organizations"]+ x-requires-administrator: true+ description: |+ Update the configuration of a+ [custom profile field](/help/custom-profile-fields) in the user's+ organization.++ The [type](/api/create-custom-profile-field#parameter-field_type)+ of a custom profile field cannot be changed.++ At most, 2 custom profile fields can have+ [`display_in_profile_summary`](/api/update-custom-profile-field#parameter-display_in_profile_summary)+ set to `true` in an organization.++ For custom profile fields with type 7 (External account) that use+ one of Zulip's configured default external account providers+ (e.g., GitHub, LinkedIn, etc.), the field's+ [`name`](/api/update-custom-profile-field#parameter-name),+ [`hint`](/api/update-custom-profile-field#parameter-hint), and+ [`field_data`](/api/update-custom-profile-field#parameter-field_data)+ cannot be changed, and attempting to do so will return an error.++ **Changes**: Before Zulip 9.0 (feature level 252), the `name`,+ `hint`, `field_data`, `required` and `display_in_profile_summary`+ parameters were all required in every request, even when their+ values were unchanged.+ parameters:+ - $ref: "#/components/parameters/CustomProfileFieldId"+ requestBody:+ content:+ application/x-www-form-urlencoded:+ schema:+ type: object+ properties:+ name:+ description: |+ The name of the custom profile field, which appears both in+ the user-facing settings UI for configuring the custom profile+ fields and in the UI displaying a user's profile.+ type: string+ example: "Programming language"+ hint:+ $ref: "#/components/schemas/CustomProfileFieldHintSchema"+ field_data:+ $ref: "#/components/schemas/CustomProfileFieldDataSchema"+ display_in_profile_summary:+ $ref: "#/components/schemas/CustomProfileFieldDisplayInProfileSummarySchema"+ required:+ $ref: "#/components/schemas/CustomProfileFieldRequiredSchema"+ editable_by_user:+ $ref: "#/components/schemas/CustomProfileFieldEditableByUserSchema"+ use_for_user_matching:+ $ref: "#/components/schemas/CustomProfileFieldUseForUserMatchingSchema"+ encoding:+ field_data:+ contentType: application/json+ display_in_profile_summary:+ contentType: application/json+ required:+ contentType: application/json+ editable_by_user:+ contentType: application/json+ use_for_user_matching:+ contentType: application/json+ responses:+ "200":+ $ref: "#/components/responses/SimpleSuccess"+ "400":+ description: Bad request.+ content:+ application/json:+ schema:+ oneOf:+ - allOf:+ - $ref: "#/components/schemas/CodedError"+ - example:+ {+ "code": "BAD_REQUEST",+ "msg": "Field id 4 not found.",+ "result": "error",+ }+ description: |+ A typical failed JSON response for when there is no custom profile+ field with the requested ID:+ - allOf:+ - $ref: "#/components/schemas/CodedError"+ - example:+ {+ "code": "BAD_REQUEST",+ "msg": "A field with that label already exists.",+ "result": "error",+ }+ description: |+ A typical failed JSON response for when another custom profile field+ already uses the requested name:+ - allOf:+ - $ref: "#/components/schemas/CodedError"+ - example:+ {+ "code": "BAD_REQUEST",+ "msg": "Only 2 custom profile fields can be displayed in the profile summary.",+ "result": "error",+ }+ description: |+ A typical failed JSON response for when setting+ `display_in_profile_summary` to `true` would exceed the+ organization's limit of 2 such fields:+ - allOf:+ - $ref: "#/components/schemas/CodedError"+ - example:+ {+ "code": "BAD_REQUEST",+ "msg": "Default custom field cannot be updated.",+ "result": "error",+ }+ description: |+ A typical failed JSON response for when attempting to change the+ `name`, `hint`, or `field_data` of a default external account field:+ delete:+ operationId: delete-custom-profile-field+ summary: Delete a custom profile field+ tags: ["server_and_organizations"]+ x-requires-administrator: true+ description: |+ Delete a [custom profile field](/help/custom-profile-fields) in+ the user's organization.++ This will also permanently delete any value configured for the+ custom profile field from every user profile in the database.+ Therefore, it's recommended that clients warn the active user of+ the related data removal before submitting the request, e.g.,+ notify them of how many users will have their profile data+ deleted as a result of deleting the custom profile field.+ parameters:+ - $ref: "#/components/parameters/CustomProfileFieldId"+ responses:+ "200":+ $ref: "#/components/responses/SimpleSuccess"+ "400":+ description: Bad request.+ content:+ application/json:+ schema:+ allOf:+ - $ref: "#/components/schemas/CodedError"+ - example:+ {+ "code": "BAD_REQUEST",+ "msg": "Field id 4 not found.",+ "result": "error",+ }+ description: |+ A typical failed JSON response for when there is no custom profile+ field with the requested ID:/realm/user_settings_defaults:patch:operationId: update-realm-user-settings-defaults@@ -28185,6 +28343,10 @@ components:dropdown UI for individual users to select an option.The interface for field type 7 is not yet stabilized.++ See [profile field types](/help/custom-profile-fields#profile-field-types)+ or the [`field_type` parameter](/api/create-custom-profile-field#parameter-field_type)+ for what each field type number means.type: objectexample:{@@ -31713,3 +31875,12 @@ components:type: integerexample: 17required: true+ CustomProfileFieldId:+ name: field_id+ in: path+ description: |+ The ID of the target custom profile field.+ schema:+ type: integer+ example: 4+ required: truediff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.pyindex 773a3afc0cc..94dcabdfc4d 100644--- a/zerver/tests/test_openapi.py+++ b/zerver/tests/test_openapi.py@@ -228,7 +228,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):"/bots","/bots/{bot_id}",#### These "organization settings" endpoints have low value to document:- "/realm/profile_fields/{field_id}","/realm/icon","/realm/logo","/realm/subdomain/{subdomain}",