docs: clarify v2 contact API request body shapes (#1089)#7552
docs: clarify v2 contact API request body shapes (#1089)#7552
Conversation
WalkthroughThis change updates OpenAPI documentation across three files to clarify the request payload structure for contact management endpoints. The single contact creation endpoint ( 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/api-v2-reference/openapi.yml`:
- Around line 1389-1394: The YAML description block for the endpoint is
malformed because the multiline text includes a colon ("shape:") which YAML
parses as a new mapping key; update the description value (the "description" key
shown in the diff) to use a block scalar indicator (e.g., add "|") immediately
after description: so the entire multiline paragraph becomes a single scalar
value, preserving the existing wording and line breaks.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: b09ff443-6a91-4610-9ac1-f7a55a89c5f4
📒 Files selected for processing (3)
apps/web/modules/ee/contacts/api/v2/management/contacts/bulk/lib/openapi.tsapps/web/modules/ee/contacts/api/v2/management/contacts/lib/openapi.tsdocs/api-v2-reference/openapi.yml
|
2 participants
What does this PR do?
Fixes #1089
This PR clarifies the request body shapes for the V2 contacts endpoints in the API docs.
While investigating the issue, I verified that the current bulk endpoint
PUT /api/v2/management/contacts/bulkstill works with the nested payload shape shown in the cURL example:environmentIdcontacts[]contacts[].attributes[]contacts[].attributes[].attributeKeycontacts[].attributes[].valueThe confusion came from the docs experience around the two contacts endpoints:
POST /management/contactsexpects a top-levelattributesobjectPUT /management/contacts/bulkexpectscontacts[].attributes[]The issue report showed a
422response withattributesmarked as required, which matches the single-contact request shape more closely than the bulk request shape. To make that distinction clearer, this PR updates the endpoint descriptions and request-body descriptions in the generated OpenAPI source and the checked-in OpenAPI YAML.Changes made:
PUT /management/contacts/bulkrequires the nested bulk payload shape and does not accept a top-levelattributesobjectPOST /management/contactsis the single-contact endpoint and uses a top-levelattributesobjectHow should this be tested?
PUT /management/contacts/bulkand confirm the description clearly states that the endpoint expectscontacts[].attributes[]POST /management/contactsand confirm the description clearly states that the endpoint expects a top-levelattributesobjectChecklist
Required
pnpm buildconsole.logsgit pull origin mainAppreciated