Response headers

[andrewkoltsov]

Feature Request

Description

drf-yasg currently lacks support for documenting response headers in the OpenAPI schema. While it allows detailed response body and status code documentation, there’s no way to define headers returned by an endpoint — such as X-RateLimit-Remaining, X-Custom-Token, or Retry-After.

This is a limitation especially for APIs that rely on headers for authentication flows, pagination, or rate limiting.

Describe the solution you'd like

I’d like to be able to add documented response headers per status code using swagger_auto_schema, something like:

@swagger_auto_schema(
    responses={
        200: openapi.Response(
            description="OK",
            headers={
                'X-My-Header': openapi.Header(
                    description="Some header",
                    type=openapi.TYPE_STRING
                )
            }
        )
    }
)

Describe alternatives you've considered

• Using extensions={"x-headers": ...} to add custom vendor extensions — but these are not rendered in Swagger UI and not standard.
• Writing response headers in operation_description or manually documenting them outside the schema.
• Switching to tools that support OpenAPI 3.0+ (like drf-spectacular), but I’d prefer to keep using drf-yasg for compatibility reasons.