Разве django-rest-swagger не работает с moderializers?

Я отправился с документацией на django-rest-swagger страница github, точнее, часть под названием "Как это сделать работает". Он показывает, что вы можете определить свои собственные параметры для вашего априори отдыха, и эти параметры отображаются на вашей странице документа swagger.

Пример комментария выглядит примерно так:

"""    
This text is the description for this API    
param1 -- A first parameter    
param2 -- A second parameter    
"""

Я могу заставить это работать, но моя проблема заключается в том, как указать, требуется ли переменная, ее тип параметра и тип данных. На странице github отображается примерное изображение о том, как может выглядеть ваш документ swagger, и у них есть информация, о которой я только что упомянул. Но когда я комментирую свои пользовательские параметры, как показано на примере, мои параметры просто отображаются как тип параметра: "запрос", тип данных: пуст, и он не отображается "обязательно".

Ближайшая вещь, которую я нашел для ответа, была в qaru.site/info/450214/.... Похоже, что поставщик ответов говорит, что django-rest-swagger генерирует свою документацию, автоматически проверяя ваши сериализаторы (что хорошо), и что моделиризаторы не будут содержать достаточной информации для django-rest-swagger, чтобы правильно вывести критерии, упомянутые мной выше. Я понимаю, что он не может понять этот критерий, но для меня должен быть какой-то способ указать его вручную.

Правильно ли, что django-rest-swagger будет показывать только то, что я хочу, если бы я переписал свои моделиризаторы как просто сериализаторы? Невозможно ли мне вручную описать django-rest-swagger, какой тип параметра параметра и тип данных должны быть, и если это необходимо?

Я знаю, что мне здесь что-то не хватает. Я использую классные представления и modelserializers, которые почти идентичны примерам в учебниках django-rest-framework. Вполне возможно, что я просто не понимаю понятия "типы параметров" в этом контексте. Мой API отлично работает, и я не хочу переписывать свои моделиризаторы для сериализаторов, чтобы я мог получить лучшую автоматическую документацию через swagger.

Ответы

Ответ 1

ModelSerializers - это правильный способ пойти с DR-Swagger. Это может быть немного хитроумным преследованием именно там, где извлекаются разные поля Swagger. Мне часто приходилось возвращаться к отладке через процесс рендеринга страницы, чтобы выяснить, откуда это происходит.

В свою очередь:

Требуется? происходит из параметра Field.required(либо установленного в модели, либо поля Serializer). Описание происходит из параметра Field.help_text.

В сериализации DRF нового стиля, текст описания поступает из dosstring ViewSet. Если вам нужны документы, специфичные для метода, вам необходимо переопределить docstring для отдельных методов, например. retrieve:

def retrieve(self, request, *args, **kwargs):
    """Retrieve a FooBar"""
    return super().retrieve(request, *args, **kwargs)

Следует отметить, что DR-Swagger перенесена на использование новой логики схемы DRF в версии 2.0 (с DRF версии 3.5), которая по-прежнему имеет несколько грубых краев. Я рекомендую придерживаться DR-Swagger версии 0.3.x, которая (хотя и устарела) имеет больше возможностей и, по моему опыту, более надежную сериализацию.

Ответ 2

В большинстве случаев ModelSerializer - это то, что вам нужно, потому что оно может быть настроено в соответствии с вашими потребностями. В идеальной ситуации вы должны определить все свои ограничения, такие как требуемый атрибут в поле, в вашем классе модели, но бывают случаи, когда это невозможно по архитектуре, тогда вы можете переопределить такое поле в подклассе ModelSerializer

from django.contrib.auth import get_user_model
from rest_framework import serializers


class UserSerializer(serializers.ModelSerializer):
    first_name = serializers.CharField(required=True)
    last_name = serializers.CharField(required=True)

    class Meta:
        model = get_user_model()

В приведенном выше примере я сериализую стандартную модель пользователя из Django и переопределяю атрибуты требуемые, поэтому теперь требуются first_name и last_name.

Конечно, бывают случаи, когда трудно или невозможно использовать ModelSerializer, тогда вы всегда можете отказаться от подкласса Serializer

Ответ 3

В коде, который у вас есть:

""
Этот текст является описанием для этого API
param1 - Первый параметр
param2 - Второй параметр
""

Try:

"" Этот текст является описанием для этого API
param1 - Первый параметр
param2 - Второй параметр
""

Я нашел, что некоторые плагины python и/или Django нуждаются в первой строке docstring, которая является первой с открытием трех двойных кавычек, которая также будет линией, которая запускает документацию. Вы даже можете не попробовать пробел между последней двойной кавычкой и T.