Заранее прошу прощения, мне лень писать статью с скриншотами сваггера и с реальным кодом, поэтому пишу сразу без правок и вычиток. Если будет интерес, возможно, когда-нибудь оформлю в виде статьи на Хабре.
Этот пост - ответ на статью https://habr.com/ru/companies/amvera/articles/843232/
Статья хороша. Вот только есть одно очень большое НО, и это - декораторы: extend_schema и т.п.
1. Декораторы - это плохо 🟧
drf-spectacular
- это уже третья библиотека для swagger в проекте, который я веду. Сначала был django-rest-swagger - в нём документация велась с помощь doc-string
. В какой-то момент эта библиотека передала эстафету библиотеке drf-yasg в ней уже были декораторы. Счастье было долгим, но нужна была поддержка OpenAPI v3. Всем желающим drf-yasg
предложил перейти на drf-spectacular.
Мне дважды пришлось переписывать документацию к swagger и мне это не понравилось, т.к. проект большой.
К счастью, drf-spectacular
(далее spectacular) спроектирован так, что если API написан правильно, то декораторы вообще не нужны.
2. GenericAPIView
и GenericViewSet
- это хорошо ✅
Достаточно унаследовать свои вьюхи от указанных классов и spectacular сам извлечёт необходимые сведения из get_queryset
и get_serializer_class
.
Т.е. можно написать такой код и swagger
сформирует правильную документацию
def get_serializer_class(self):
if self.action == "create":
return CreateSerializer
if self.action == "retrive":
return RetriveSerializer
return super().get_serializer_class()
3. Иногда декораторы - это необходимость ✅
Возникает вопрос, зачем нужны декораторы, если spectacular
справляется сам. Иногда нужно писать API, которое берёт данные не из БД. Разного рода API-калькуляторы, или API-посредники, которые возвращают вычисленные данные или полученные из вне. В этом случае, приходится наследовать вьюху от APIView
. Тут без декоратора не обойтись.
4. SerializerMethodField
с простыми типами - это хорошо ✅
Если поля имеют простые типы: IntergerField
, CharField
, то spectacular справляется очень хорошо. Но если используется SerializerMethodField
, то ему уже нужны подсказки. Для простых типов это просто, достаточно указать тип возвращаемой функции.
class MySerializer(Serializer):
a = IntegerField()
b = IntegerField()
sum = SerializerMethodField()
def get_sum(self, obj) -> int: # Возвращаемый тип: int
return obj.a + obj.b
Этот способ хорошо работает, даже если нужно вернуть список простых объектов, например List[str]
5. SerializerMethodField для объектов - это плохо 🟧
Со сложными объектами, не так всё просто. К примеру, у нас есть такой код
# 🟧
class ExperimentSerializer(DummySerializer):
entity = SerializerMethodField()
@staticmethod
def get_entity(_) -> dict:
return {"a": 1, "b": "2"}
Как spectacular должен догадаться, как называются поля и какого типа у них значения? Без выполнения кода это не возможно.
Опытные разработчики могут догадаться, как ему подсказать
# ⁉
class EntityDict(TypedDict):
a: int
b: str
class ExperimentSerializer(Serializer):
entity = SerializerMethodField()
@staticmethod
def get_entity(_) -> EntityDict:
return {"a": 1, "b": "2"}
Такое работает, в swagger появится правильное описание. Но иногда нужно получить данные из другого сериализатора:
# 🟧
class EntityDict(TypedDict):
a: int
b: str
class EntitySerializer(Serializer):
a = IntegerField()
b = CharField()
class ExperimentSerializer(Serializer):
entity = SerializerMethodField()
@staticmethod
def get_entity(_) -> EntityDict:
return EntitySerializer(obj.entity).data
Работает, но тут есть нарушение DRY. Попробуем по другому:
# 🟧
class EntitySerializer(Serializer):
a = IntegerField()
b = CharField()
class ExperimentSerializer(Serializer):
entity = SerializerMethodField()
@staticmethod
def get_entity(_) -> EntitySerializer:
return EntitySerializer(obj.entity).data
От дублирования избавились, swagger всё ещё работает, но тип метода get_entity
не соответствует возвращаемым данным.
В общем, для своего проекта я написал класс DataSerializerField, который решает эту проблему.
Пример использования:
# ✅
class EntitySerializer(Serializer):
a = IntegerField()
b = CharField()
class ExperimentSerializer(Serializer):
entity = DataSerializerField(EntitySerializer)
@staticmethod
def get_entity_data(_):
return obj.entity
Я мог бы написать ещё много о возможностях spectacular, но это как-нибудь в следующий раз.
Top comments (0)