Установка и настройка drf-yasg для Swagger

Документирование API — важная часть разработки, ибо каким бы крутым ваш API ни был, без документации он — как тайна, покрытая мраком. Swagger, в частности, через библиотеку drf-yasg, поможет нам автоматически генерировать описания API на основании существующего кода.

Что такое Swagger и зачем он нам нужен?

Swagger — это инструмент для документирования и тестирования REST API. Он позволяет:

• Генерировать автоматическую документацию на основе определений эндпоинтов.
• Упрощать тестирование с помощью интерфейса Swagger UI.
• Обеспечивать понятность и прозрачность вашего API для разработчиков.

Представьте себе, что в мире программирования Swagger — это толковый словарь для вашего API, который позволяет быстрее находить нужные маршруты, понять их логику, а также протестировать всё без сторонних клиентов вроде Postman.

Установка и настройка drf-yasg

Шаг 1: установка пакета

Чтобы начать работу с drf-yasg, его нужно сначала установить. Выполните следующую команду в терминале:

pip install drf-yasg

Шаг 2: настройка проекта

Окей, библиотека установлена. Но как заставить её работать с нашим проектом? Чтобы drf-yasg мог генерировать документацию, нам нужно внести изменения в файл urls.py.

Откройте файл urls.py в корне вашего проекта и выполните следующие шаги.

Импорты

Сначала импортируем нужные модули:

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

Настройка schema_view

Теперь мы настроим schema_view, который будет содержать информацию о вашей документации:

schema_view = get_schema_view(
    openapi.Info(
        title="Example API",       # Название вашего API
        default_version='v1',      # Версия API
        description="API для нашего проекта",  # Краткое описание
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="support@yourapp.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),  # Кому разрешён доступ к документации
)

Добавление маршрутов

Теперь добавим маршруты для Swagger UI и документации в формате YAML/JSON. Вставьте следующий код в urlpatterns:

from django.urls import path

urlpatterns = [
    # Ваши маршруты...
    path('swagger/', 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'),
    path('swagger.yaml', schema_view.without_ui(cache_timeout=0), name='schema-yaml'),
    path('swagger.json', schema_view.without_ui(cache_timeout=0), name='schema-json'),
]

Итак, у нас есть три важных маршрута:

1. /swagger/ — открывает Swagger UI, интерактивное представление документации.
2. /swagger.yaml и /swagger.json — предоставляют исходные данные документации.
3. /redoc/ — ссылочка на другой интерфейс документации, о нём поговорим дальше.

Шаг 3: запуск Swagger UI

Запустите локальный сервер командой:

python manage.py runserver

И откройте в браузере URL http://127.0.0.1:8000/swagger/. Что вы видите? Красивую страницу, на которой отображаются все ваши эндпоинты! Она автоматически подгружается из кода ваших представлений (views).

Шаг 4: настройка документации

Всё настроено, но документация пока что выглядит... скажем, минималистично. Это потому, что drf-yasg берёт данные из вашего кода. Чтобы улучшить генерацию документации, можно использовать специальные аннотации.

Применение декоратора @swagger_auto_schema

Допустим, у нас есть простое представление в DRF:

from rest_framework.views import APIView
from rest_framework.response import Response

class HelloWorldView(APIView):
    def get(self, request):
        return Response({"message": "Hello, world!"})

Чтобы задокументировать этот эндпоинт, мы добавим декоратор @swagger_auto_schema:

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    operation_description="Получение приветственного сообщения",
    responses={200: "Сообщение успешно получено"}
)
class HelloWorldView(APIView):
    def get(self, request):
        return Response({"message": "Hello, world!"})

Теперь, если вы обновите Swagger UI, вы увидите описание этого эндпоинта.

Шаг 5: улучшение документации с помощью сериализаторов

Вы также можете указать сериализатор, чтобы Swagger генерировал более подробную информацию о входных и выходных данных.

Пример:

from rest_framework import serializers

class HelloSerializer(serializers.Serializer):
    name = serializers.CharField(max_length=100)

@swagger_auto_schema(
    operation_description="Получение приветственного сообщения",
    responses={200: HelloSerializer},
    query_serializer=HelloSerializer  # Описание входных параметров
)
class HelloWorldView(APIView):
    def get(self, request):
        name = request.query_params.get('name', 'world')
        return Response({"message": f"Hello, {name}!"})

Теперь Swagger отобразит информацию о параметре name и выходных данных.

Частые ошибки и способы их избежать

Проблема с маршрутом /swagger/ Если страница Swagger не отображается, проверьте:

1. Вы добавили path('swagger/', schema_view.with_ui(...)) в urls.py?
2. Вы установили drf-yasg? (ну, на всякий случай, спросим).
3. Проверьте, что в ваших представлениях правильно настроены методы и сериализаторы.

Проблема с автоматической генерацией документации Если какие-то эндпоинты не отображаются, убедитесь, что:

• Они наследуются от APIView или ViewSet.
• Вы используете маршрутизацию DRF (например, SimpleRouter).

Практическое применение

Теперь ваш API — не просто набор эндпоинтов, а полноценный инструмент, готовый к использованию! Swagger UI позволяет:

• Команде тестировщиков мгновенно понять структуру вашего API.
• Быстро обнаружить несоответствия между документацией и кодом.
• Упростить жизнь фронтенд-разработчикам, ведь тестировать API-коды стало намного проще.

Хотите, чтобы документация всегда соответствовала реальности? Настройте CI/CD, чтобы Swagger автоматически обновлялся при каждом коммите. Отныне ваша команда будет работать быстрее и счастливее!