[CSM Portal] Document account/project contacts-search endpoints in entity-service OpenAPI spec

[rksk]

Purpose

POST /accounts/{id}/contacts/search and POST /projects/{id}/contacts/search are implemented and routed in the Go entity-service (handlers, services, and routes.go), but were never added to openapi.yaml. The Ballerina entity-service already documents both equivalent paths.

Goals

Bring entity-service/openapi.yaml in sync with the code so both contacts-search endpoints are discoverable in the spec, matching the request/response shapes already used by the handlers.

Approach

Added POST /accounts/{id}/contacts/search and POST /projects/{id}/contacts/search path entries plus their request/response schemas (SearchAccountContactsRequest/Response, AccountContact, SearchProjectContactsRequest/Response, ProjectContact), following the existing conventions in the file (same style as the neighboring /accounts/search and /projects/search entries). Schema fields were checked against the actual Go structs (internal/domain/entity.go) to keep the spec accurate. Docs-only change — no code touched.

User stories

N/A — documentation-only change, no behavior change.

Release note

N/A — internal API documentation fix, not a user-facing change.

Documentation

N/A — this PR is the documentation fix (OpenAPI spec).

Automation tests

• Unit tests: N/A, no code changed.
• Integration tests: N/A, no code changed. Validated the YAML parses (python3 -c "import yaml; yaml.safe_load(...)") and go vet ./... remains clean.

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes
• Ran FindSecurityBugs plugin and verified report? N/A — Go project, no code changed; go vet ./... ran clean.
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes

Samples

N/A

Related PRs

N/A

Migrations (if applicable)

N/A

Test environment

N/A — docs-only change.

Learning

N/A

Summary by CodeRabbit

• New Features
  • Added contact search for accounts and projects.
  • Supports case-insensitive searches by contact name or email.
  • Added pagination details, including total results, limit, and offset.
  • Added clear responses for invalid requests, missing resources, and server errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 80df6f21-c4d7-4ec1-95dd-1fba22b6671e

📥 Commits

Reviewing files that changed from the base of the PR and between 88a3ce3 and 7e9494a.

📒 Files selected for processing (1)

• entity-service/openapi.yaml

---

📝 Walkthrough

Walkthrough

Adds ServiceNow-only OpenAPI contracts for account and project contact search, including paginated request filters, contact response schemas, operation definitions, and documented success and error responses.

Changes

Contact search API

Layer / File(s)	Summary
Contact search schemas entity-service/openapi.yaml	Adds request and response schemas for account and project contact searches, including case-insensitive searchQuery, pagination, contact arrays, and total/limit/offset metadata.
Contact search operations entity-service/openapi.yaml	Adds POST endpoints for account and project contact searches with UUID resource identifiers, optional request bodies, and 200, 400, 404, and 500 responses.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• wso2-open-operations/cs-tools#1191: Implements the corresponding ServiceNow contact-search endpoints.
• wso2-open-operations/cs-tools#1202: Adds passthrough handlers and client methods for the same routes.

Suggested labels: Type/Improvement, Area/Backend, App/CSM Portal

Suggested reviewers: rashmika998

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: documenting the contacts-search endpoints in the entity-service OpenAPI spec.
Description check	✅ Passed	The description follows the template and includes all required sections with enough detail for a docs-only OpenAPI change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Checkov (3.3.8)

entity-service/openapi.yaml

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}