Встановлення та налаштування 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 автоматично оновлювався при кожному коміті. Відтепер ваша команда працюватиме швидше та щасливіше!