Использование Swagger UI для тестирования API

Ну что ж, отличная новость — мы уже подключили Swagger к нашему проекту, и теперь настало время использовать эту мощную штуковину для тестирования наших API. В этой лекции мы разберемся, чем полезен Swagger UI, как его правильно использовать для тестирования HTTP-запросов и ответов, и посмотрим на это всё в действии. Готовьтесь, будет интересно!

Что такое Swagger UI?

Swagger UI — это интерфейс для работы с описанным API. Да-да, он не только показывает структуру эндпоинтов (что уже полезно), но и позволяет прямо из браузера отправлять запросы и получать ответы от сервера. Представьте, что это как Postman, но встроенный в ваш проект. Все, что вам нужно, уже на одном экране.

Почему это так круто?

• Вы можете быстро проверить, работают ли ваши эндпоинты.
• Swagger UI экономит время, позволяя отправлять запросы без написания кода или использования сторонних инструментов.
• Это упрощает обмен API с вашей командой или заказчиком, предоставляя ready-to-go интерфейс.

Настройка Swagger UI для тестирования

Перед тем как начать тестировать, давайте убедимся, что Swagger UI уже настроен и доступен в нашем проекте.

Пример настройки

Вот как может выглядеть базовая настройка вашего Django-проекта с drf-yasg:

# urls.py

from django.contrib import admin
from django.urls import path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# Настраиваем OpenAPI Schema
schema_view = get_schema_view(
    openapi.Info(
        title="API Документация",
        default_version='v1',
        description="Описание вашего API",
        terms_of_service="https://www.example.com/terms/",
        contact=openapi.Contact(email="support@example.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('your_app.urls')),  # Ваши API эндпоинты
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]

После настройки перейдите по адресу http://127.0.0.1:8000/swagger/, и если вы всё сделали правильно, вас встретит интерфейс Swagger UI.

Работа со Swagger UI: тестирование API в действии

Переходим к самому интересному — использованию Swagger UI для тестирования.

Шаг 1: Ориентируемся в Swagger UI

Когда вы заходите на страницу Swagger UI, вы увидите схему своего API. Она состоит из:

• Коллекции эндпоинтов, сгруппированных по названию (например, users, articles).
• Подробных спецификаций для каждого эндпоинта: метод (GET, POST и т.д.), параметры запроса, тело (если нужно), и ожидаемые ответы.

Это выглядит примерно так:

GET /api/v1/users/
POST /api/v1/users/
GET /api/v1/users/{id}/
PUT /api/v1/users/{id}/
DELETE /api/v1/users/{id}/

Каждый из этих эндпоинтов представляет определенную операцию, а рядом с ними есть кнопка "Try it out".

Шаг 2: Используем "Try it out"

Нажмите кнопку "Try it out" для любого эндпоинта. Например, давайте проверим список пользователей через GET /api/v1/users/.

1. После нажатия откроется форма с необходимыми параметрами. Для этого эндпоинта, возможно, параметры не потребуются.
2. Нажмите "Execute" (это как нажать на кнопку "отправить запрос").

Swagger UI отправит запрос на ваш сервер и покажет:

• URL запроса, который был сгенерирован.
• Тело запроса (если оно есть).
• Ответ сервера: статус ответа (например, 200 OK) и данные, которые вернул сервер в формате JSON.

Пример вывода:

[
    {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com"
    },
    {
        "id": 2,
        "username": "john_doe",
        "email": "john_doe@example.com"
    }
]

Шаг 3: Передаем параметры в запросах

Попробуем другой эндпоинт, например, POST /api/v1/users/ для создания нового пользователя.

1. Выберите эндпоинт и нажмите "Try it out".
2. В Swagger UI появится форма для ввода данных. Введите данные для нового пользователя:

      {
          "username": "new_user",
          "email": "new_user@example.com"
      }
   

3. Нажмите "Execute", и вы увидите ответ сервера. Он может быть, например:
   • Успешный 201 Created, с созданным объектом.
   • Ошибка 400 Bad Request, если пропущены обязательные поля.

Если у эндпоинта есть Query Params (например, фильтрация), их также легко указать через форму Swagger UI.

Шаг 4: Тестирование более сложных запросов

Swagger UI также поддерживает работу с эндпоинтами, которые принимают более сложные запросы, такие как авторизация.

Пример: тестирование эндпоинта с авторизацией Если ваш эндпоинт требует токен (например, для JWT):

1. Найдите поле "Authorize" в верхнем правом углу Swagger.
2. Введите ваш токен:

   Bearer YOUR_ACCESS_TOKEN
   

3. Теперь все защищенные эндпоинты будут тестироваться с этим токеном.

Для примера, вы можете протестировать GET /api/v1/protected-data/, который вернет доступные данные только для авторизованных пользователей.

Шаг 5: Анализ ответов сервера

Swagger UI также помогает анализировать ваши ответы:

• Если ответ от сервера отличается от ожидаемого формата в Swagger, это сигнал, что нужно проверить ваш код.
• Вы можете видеть все ключи и значения JSON-ответа, что удобно для разработки и дальнейшего тестирования.

Ошибки и типичные проблемы

• Ошибка "CORS": если ваш фронтенд и бекенд находятся на разных доменах, вы можете столкнуться с ошибкой CORS. Убедитесь, что CORS настроен в проекте Django (например, с использованием django-cors-headers).
• Ошибка 401 Unauthorized: это означает, что вы забыли передать токен или передали его неверно. Проверьте поле Authorize.
• Неверные параметры запроса: если эндпоинт ожидает определенные параметры, а вы их не передали, Swagger покажет соответствующую ошибку (например, 400 Bad Request).

Как Swagger UI упрощает жизнь

1. Быстрое тестирование: не нужно писать дополнительные скрипты или использовать сторонние инструменты — всё прямо в браузере.
2. Документирование одновременно с тестированием: когда вы создаете или меняете эндпоинты, вы сразу видите их в Swagger UI.
3. Работа в команде: ваши коллеги-разработчики смогут оценить эндпоинты с минимальными усилиями, даже если они не знакомы с проектом.

Теперь вы готовы использовать Swagger UI на практике. Убедитесь, что ваши эндпоинты работают правильно, и наслаждайтесь бесшовной работой с этим инструментом! В следующий раз мы посмотрим, как кастомизировать Swagger UI под специфику вашего проекта.