DOCSP-56401-[PYTHON]-Add-OpenAPI-Response-Documentation-to-FastAPI-Endpoints

[tmcneil-mdb]

What this PR Does?

This PR improves the OpenAPI Response Documentation. The current API documentation at /docs was incomplete due to the endpoints not being fully documented. This PR adds the responses parameter to all of the api endpoints in the movies.py file and adds a helper module to ease future maintenance.

Changes Made

• Created Response Documentation Helper @ src/utils/response_docs.py
• Added the responses parameter array to all the endpoints with the relevant responses
• Standardized error response format: Noticed some errors used a simple {"detail": "..."} format while others used a detailed format. Aligned all responses to use the detailed format matching the Express backend and the error_response.py file:

{
  "success": false,
  "message": "...",
  "error": {
    "message": "...",
    "code": "...",
    "details": "..."
  },
  "timestamp": "..."
}

• Updated unit and integration tests to match the new standardized format

Testing

No breaking changes. The only changes are to the codebase readability and the /docs page

• Changes can be seen at localhost:####/docs

Jira

This ticket originated from this suggestion.

[cbullinger]

nice!

[cbullinger]

i think this is overwriting the FASTAPI_400_INVALID_SEARCH_OPERATOR key

[cbullinger]

yep. from Augment:

Issue: The /api/v1/movies/search endpoint can return TWO different 400 errors, but only ONE is documented in the OpenAPI schema.

Why: In the code, the responses dict has duplicate 400 keys, and the second one overwrites the first:

responses={
**SEARCH_ENDPOINT_RESPONSES, # Contains: 400: INVALID_SEARCH_OPERATOR
400: FASTAPI_400_MISSING_SEARCH_PARAMS # This OVERWRITES the above!
}

Result: When you expand the GET /api/v1/movies/search endpoint below and look at > the "400" response, you'll only see documentation for "Missing search parameters" - the "Invalid search operator" error is missing!

The two 400 errors that can occur:

Invalid search operator: "Invalid search operator 'invalid'. The search operator must be one of {'must', 'should', 'mustNot', 'filter'}."
Missing search parameters: "At least one search parameter must be provided." (This is the only one documented)

[tmcneil-mdb]

You are right. I am going to use the oneOf schema to fix that. I can see both in the api docs page, now with the fix.

What is Augment? 👀

[cbullinger]

an AI coding tool: https://www.augmentcode.com

[cbullinger]

wouldn't a svc unavailable be a 503?

[tmcneil-mdb]

Correct. Hmmm I noticed that the error responses are actually mixed. I will address that in the next commit.

[cbullinger]

This looks great! Nice job. My only suggestion might be to update the PR description so it includes the additional work standardizing responses