Интеграция Swagger в Django проект

Описание

Swagger — это технология, которая позволяет документировать REST-сервисы. Swagger поддерживает множество языков программирования и фреймворков. Также Swagger предоставляет UI для просмотра документации.

Установка

Для начала установите drf-yasg:

$ pip install drf-yasg

Теперь нам необходимо изменить наш конфигурационный файл core/settings.py:

INSTALLED_APPS = [
    ...
    'drf_yasg',
]


# Настройки для авторизации по токену
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'Token': {
            'type': 'apiKey',
            "name": "Authorization",
            "in": "header"
        }
    }
}

Далее добавляем в файл core/urls.py:

...
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi


schema_view = get_schema_view(
   openapi.Info(
      title="HeadHunter API",
      default_version='v1',
   ),
   public=True,
   permission_classes=[permissions.AllowAny],
)


urlpatterns = [
    ...
    path('schema/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    path('swagger-ui/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

Попробуйте открыть документацию своего api в браузере: http://localhost:8000/swagger-ui/

Авторизация на swagger-ui

Чтобы авторизоваться по токену необходимо:

1. Получить токен: Для этого вы должны написать свою точку входа для авторизации и получения токена в ответе. Далее отправляем на запрос на авторизацию через swagger с телом:

{
  "username": "admin",
  "password": "admin"
}

2. Копируем токен, далее нажимаем на кнопку Authorize. В открывшемся поле вставляем токен в таком виде:

Token ab7517278988581d0cf0a1af245ecc4000e22eff # У вас токен будет другой!!!

3. Нажимаем кнопку Authorize и все готово, вы авторизовались и теперь токен будет автоматически подставляться на странице swagger-ui в запросах

Важно

Если у вас view для api написаны через наследование от APIView, то необходимо переписать их на наследование от GenericAPIView или ModelViewSet. Иначе при загрузке, swagger-ui не будет видеть параметры для автогенерации json при отправке api для изменения БД Например:

from rest_framework.generics import GenericAPIView
from rest_framework.viewsets import ModelViewSet
from api.serializers import TestSerializer


class TestAPIView(GenericAPIView):
    serializer_class=TestSerializer
    ...

class TestViewSet(ModelViewSet):
    serializer_class=TestSerializer
    ...