docs: updated docs for patch suggestion endpoint

[ssilare-adobe]

OpenAPI Documentation Update: Suggestion Status Endpoint Clarification

Summary

Updated the SpaceCat OpenAPI specification to clarify the proper endpoint for updating suggestion statuses and improve documentation for the batch status update endpoint.

Problem

The API documentation was unclear about how to update suggestion statuses:

• The individual suggestion PATCH endpoint (/sites/{siteId}/opportunities/{opportunityId}/suggestions/{suggestionId}) does not support updating the status field
• Users were not aware of the batch status endpoint (/sites/{siteId}/opportunities/{opportunityId}/suggestions/status) which is the correct way to update statuses
• This caused confusion and integration errors when attempting to update suggestion statuses

Changes Made

1. Enhanced Batch Status Endpoint Documentation

File: docs/openapi/site-opportunities.yaml

• Updated the PATCH /sites/{siteId}/opportunities/{opportunityId}/suggestions/status endpoint with:
  • More descriptive summary: "Batch update suggestion status"
  • Comprehensive description explaining:
    • This is the ONLY endpoint for updating suggestion status
    • Request format requirements (id + status for each item)
    • Response format details (207 Multi-Status with individual results)
  • Added missing response codes (400, 401, 404, 429, 500, 503)
  • Improved response descriptions with details about success/failure handling

2. Clarified Individual Suggestion PATCH Endpoint

File: docs/openapi/site-opportunities.yaml

• Updated PATCH /sites/{siteId}/opportunities/{opportunityId}/suggestions/{suggestionId} to include:
  • Clear description noting that status and type fields are READ-ONLY
  • Reference to the correct batch status endpoint for status updates
  • Clarification that this endpoint only supports updating: rank, data, and kpiDeltas

3. Fixed Schema Inconsistencies

File: docs/openapi/schemas.yaml

Updated schemas to match actual implementation:

• SuggestionOperationSuccess: Added uuid field (was missing)
• SuggestionUpdateFailure: Changed id to uuid for consistency
• SuggestionStatusUpdateListResponse: Changed failure to failed in metadata (matches implementation)

4. Updated Examples

File: docs/openapi/examples.yaml

• Updated broken-backlinks-suggestions-status-update-response example to:
  • Use uuid instead of id
  • Include full suggestion object in success responses
  • Use failed instead of failure in metadata
  • Show realistic error messages

Please ensure your pull request adheres to the following guidelines:

• make sure to link the related issues in this description. Or if there's no issue created, make sure you
  describe here the problem you're solving.
• when merging / squashing, make sure the fixed issue references are visible in the commits, for easy compilation of release notes

If the PR is changing the API specification:

• make sure you add a "Not implemented yet" note the endpoint description, if the implementation is not ready
  yet. Ideally, return a 501 status code with a message explaining the feature is not implemented yet.
• make sure you add at least one example of the request and response.

If the PR is changing the API implementation or an entity exposed through the API:

• make sure you update the API specification and the examples to reflect the changes.

If the PR is introducing a new audit type:

• make sure you update the API specification with the type, schema of the audit result and an example

Related Issues

Thanks for contributing!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!