Використання 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 під специфіку твого проєкту.