Audit and refine the API documentation

[dhruvkb]

Description

Summary

Audit and update the API documentation (both in terms of the rendered HTML and the OpenAPI spec) so that request parameters and responses are correctly and fully described.

Detailed description

The API documentation regarding the return fields, their types and the query parameters is not fully accurate. Some fields are set as nullable even though they are required and always have a value.

Improving the rendered documentation will help the API consumers, and improving the openapi.yaml file will make it possible to generate correct frontend types and fetch code.

Documents

• Project Proposal
• Implementation Plan: Audit and refine the API documentation

Milestones/Issues

🚧 WIP

Prior Art

• Refactor serializers to match media models and ES indices #745