drf-spectacular: add response description

Question

How can I add description to responses in the @extend_schema decorator?

'500':
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Error'
      description: ''

Answer 1

that specific description location you are referring to is not easily available through the decorators. however, there are multiple places a description can be put.

1. @extend_schema(description='Your description') this will add the description to the view action (operation). However, this is targeted to the operation itself and not the 500 Error case.

2. adding a docstring to your Error serializer. probably what you want to do.

this part is still a bit rough as the "Error" feature is still work in progress.

Answer 2

Insa's answer and comments led me to a working solution using OpenApiResponse (requires drf-spectacular version >=0.15)

Here's some example code of how I did it:

from drf_spectacular.utils import extend_schema, OpenApiResponse
from rest_framework import generics

class MyResourceList(generics.ListCreateAPIView):

    @extend_schema(
        summary="Create a new resource",
        responses={
            201: OpenApiResponse(response=MyCustomSerializer,
                                 description='Created. New resource in response'),
            400: OpenApiResponse(description='Bad request (something invalid)'),
        },
    )
    def post(self, request, *args, **kwargs):
        """ 
        Some explanation goes here ...
        """
        return super().post(request, *args, **kwargs)

• The documentation on OpenApiResponse is here: https://drf-spectacular.readthedocs.io/en/latest/drf_spectacular.html?highlight=openapiresponse#drf_spectacular.utils.OpenApiResponse
• But the tests are actually more useful: https://github.com/tfranzel/drf-spectacular/blob/1f7cf5d8342f5ed3f619afcf92fb43e3b4ff26cb/tests/test_regressions.py#L1744