drf-spectacular: добавить описание ответа

#python-3.x #django-rest-framework

Вопрос:

Как я могу добавить описание к ответам в декораторе @extend_schema?

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

Ответ №1:

Ответ и комментарии Инсы привели меня к рабочему решению с использованием OpenApiResponse (требуется drf-эффектная версия> = 0.15)

Вот несколько примеров кода того, как я это сделал:

 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)

Документация по OpenApiResponse находится здесь: https://drf-spectacular.readthedocs.io/en/latest/drf_spectacular.html ?выделите=openapiresponse#drf_spectacular.utils.OpenApiResponse Отклик
Но тесты на самом деле более полезны: https://github.com/tfranzel/drf-spectacular/blob/1f7cf5d8342f5ed3f619afcf92fb43e3b4ff26cb/tests/test_regressions.py#L1744

1. документы там, чтобы объяснить, что возможно / ожидается. было бы невозможно показать все случаи в документе. тест явно написан в виде библиотеки примеров, то есть коротких, кратких, изолированных. большинство вариантов использования можно найти в тестах.

Ответ №2:

это конкретное местоположение описания, на которое вы ссылаетесь, нелегко получить через декораторы. однако есть несколько мест, где можно поместить описание.

@extend_schema(description='Your description') это добавит описание к действию (операции) просмотра. Однако это относится к самой операции, а не к 500 случаю ошибки.
добавление строки документа в ваш Error сериализатор. вероятно, то, что вы хотите сделать.

эта часть все еще немного грубовата, поскольку функция «Ошибка» все еще находится в стадии разработки.

1. Я использую один и тот же сериализатор для нескольких кодов ошибок (4XX, 500)

2. это может показаться простой функцией, но она сложнее, чем кажется. sry сказать, что в настоящее время это не поддерживается.

3. Есть какие-нибудь исправления до сих пор?

4. Теперь есть OpenApiResponse, чтобы обернуть сериализатор вместе со строкой описания. Эта функция была добавлена в последней версии 0.15.0.

5. @Rabarberski, взгляни на тесты для использования. вы просто оборачиваете то, что вы бы вложили extend_schema(responses=XXX) . Что касается строки документа, я буквально имел в виду строку документа с тройными кавычками в классе, которая отлично воспринимается.