Как настроить документацию Django Rest Framework без использования декораторов?

В настоящее время я работаю над проектом Django и использую Django Rest Framework (DRF) для создания API. Я интегрировал drf-pectacular для автоматической генерации документации по API, но обнаружил, что использование декораторов для настройки документации делает мою кодовую базу грязной.

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

Любые предложения, примеры или лучшие практики будут высоко оценены. Спасибо!

Вы можете использовать модуль "drf_yasg" здесь. Вам просто нужно передать docstring для ваших сериализаторов и представлений следующим образом :

class MyModelSerializer(serializer.ModelSerializer):
    """
       doc string goes here
    """
    model = MyModel
    fields = []

views.py

class MyAPIViewClass(generics.ListAPIView):
    """
       doc string goes here
    """
    permission_classes = []
    serializer_class = MyModelSerializer

так что "drf_yasg" создаст вашу документацию.

Существует несколько библиотек автоматической генерации документов для DRF, главное, чтобы вы хотите настроить свои документы.
drf-yasg использует OpenAPI 2, как сказано в документации https://drf-yasg.readthedocs.io/en/stable/readme.html.
Но drf-pectacular использует OpenAPI 3, как сказано в документации https://drf-spectacular.readthedocs.io/en/latest/readme.html

в drf-yasg документации говорится, что если вы хотите использовать OpenAPI 3, используйте drf-pectacular https://drf-yasg.readthedocs.io/en/stable/readme.html#openapi-3-0-note

Но в целом, если вы хотите настроить свои документы, большинство подобных библиотек используют decorators для настройки вывода документов.

Здесь вы можете прочитать, как настроить ваши документы с помощью drf-yasg: https://drf-yasg.readthedocs.io/en/stable/custom_spec.html

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

Вернуться на верх