OpenAPI Schemas when request/response objects differ

[ChristopherChudzicki]

When constructing an OpenAPI schema for a ModelViewSet, drf-spectacular has particular difficulty when a serializer field treats request/response data differently. An example of this is LearningResource.topics: Responses serializer topics as objects, but requests (assuming #34 is merged) expect integer topic ids or objects:

// GET /api/v1/learningpaths/39/
{
  "id": 39,
  "topics": [
      { "id": 15, "name": "Systems Engineering" },
      { "id": 12, "name": "Physics" }
  ]
  // ...
}
// POST /api/v1/learningpaths/
{
  "topics": [15, 12] // Or objects, though IDs are seem convenient
}

Issue: But drf-spectacular reports topics as an object in both cases.

[ChristopherChudzicki]

Any solution to this will require enabling COMPONENT_SPLIT_REQUEST as a first step; we should do that anyway, but it is not sufficient to resolve this issue.

Then, I can think of a few ways to deal with the current spec's inaccurate modeling:

1. Decide we don't care: Just use full topic objects when making POST/PATCH etc requests.
2. Use separate fields for requests/responses
   • topics: obj[], read-only for responses
   • topic_ids: int[], write-only for requests
3. Possibly fixable by anotating view methods with @extend_schema and separate request/response serializers. This would be quite manual, I think, and require creating those separate serializers.
4. Use a custom field meant to handle this case, and register the custom field as an extension in drf-spectacular.
   • PresentablePrimaryKeyRelatedField is a third-party field that does this, and drf-spectacular has an example "blueprint" for this field