Fix OpenAPI schema for TokenObtainPairView

[Shrikantgiri25]

Problem

The OpenAPI / schema generated for TokenObtainPairView can be misleading.

TokenObtainPairSerializer dynamically adds the access and refresh
fields during validate(), but those fields are not declared on the serializer
itself. Schema generators that rely on serializer field introspection (for
example, drf-yasg or DRF core schema generation) may therefore produce an
incomplete or incorrect response schema.

In practice, the token obtain endpoint returns a JSON response containing both
tokens::

{
"access": "",
"refresh": ""
}

However, this response shape is not always reflected in the generated schema.

This issue has been reported previously:

• Issue with schema generation #246

Solution

Explicitly declare the access and refresh fields on
TokenObtainPairSerializer as read-only serializer fields.

These values are already returned by the serializer at runtime; this change
simply makes the serializer definition accurately reflect the real response
payload for schema generation purposes.

Why this change is safe

• No change to runtime behavior
• No change to token generation logic
• Fully backward compatible
• Minimal and non-invasive diff
• Improves OpenAPI / schema accuracy for downstream tooling

Tests

A test was added to ensure that:

• access and refresh fields exist on the serializer
• Both fields are marked as read_only=True
• Runtime validation and token issuance continue to behave as expected

This helps prevent regressions and ensures the serializer remains compatible
with schema generators.

Example schema output (after change)

Example OpenAPI schema generated after this change (drf-yasg / DRF schema)::

  openapi: 3.0.2
  paths:
    /api/token/:
      post:
        responses:
          '200':
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/TokenObtainPair'

  components:
    schemas:
      TokenObtainPair:
        type: object
        properties:
          refresh:
            type: string
            readOnly: true
          access:
            type: string
            readOnly: true
          username:
            type: string
            writeOnly: true
          password:
            type: string
            writeOnly: true
        required:
        - username
        - password

Summary

This change aligns the TokenObtainPairSerializer definition with its actual
response payload, improving schema correctness while keeping runtime behavior
unchanged.

[Andrew-Chen-Wang]

ty

should this be done for any other serializer?

[Shrikantgiri25]

ty

should this be done for any other serializer?

Yes, TokenObtainSlidingSerializer needs the same fix as TokenObtainPairSerializer. I’ve added:
token = serializers.CharField(read_only=True)
This solves the same issue - the token field is dynamically added in validate() but wasn’t declared, so schema generators didn’t see it.
I’ve used serializers.CharField(read_only=True) in both serializers to maintain consistency across the serializers and ensure correct OpenAPI / Swagger schema generation. I’ve checked all other serializers; they are already correct and don’t need this change.