Використання Swagger і Redoc для тестування API

У світі розробки API є одне золоте правило: якщо щось добре задокументовано, то половина роботи вже зроблена. Сьогодні ми поговоримо про те, як Swagger і Redoc допомагають не тільки документувати, але й тестувати ваші API. Це буде практичне заняття, де ми не тільки поговоримо про важливість документації, але й побачимо, як використовувати Swagger і Redoc для відправлення запитів, тестування та аналізу.

Swagger UI: тестування API

Swagger UI — це потужний інструмент для тестування API прямо через веб-інтерфейс. Уявіть його як інтерактивний Postman, який завжди знає специфікації вашого API (ну, якщо ви все модеруєте, звісно).

Вступ до тестування через Swagger UI

Swagger UI дозволяє:

• Відправляти запити до ендпоінтів;
• Переглядати запити та відповіді в реальному часі;
• Перевіряти поведінку ендпоінтів на різних методах HTTP (GET, POST, PUT, DELETE і т.д.);
• Легко змінювати параметри запиту, тіло або заголовки прямо в інтерфейсі.

Щоб протестувати ендпоінт, вам знадобиться:

1. Перейти на URL Swagger UI вашого застосунку. Наприклад, http://127.0.0.1:8000/swagger/.
2. Знайти ендпоінт, який ви хочете протестувати.
3. Розгорнути його і натиснути кнопку "Try it out".
4. Вказати параметри (якщо вони потрібні) і натиснути "Execute".

Практичне тестування ендпоінтів

Давайте протестуємо простий ендпоінт, який повертає список книг з нашої моделі Book.

Приклад коду ендпоінта:

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

class BookListView(APIView):
    def get(self, request):
        books = [
            {"id": 1, "title": "1984", "author": "George Orwell"},
            {"id": 2, "title": "To Kill a Mockingbird", "author": "Harper Lee"}
        ]
        return Response(books)

Додайте маршрут для цього представлення в urls.py:

from django.urls import path
from .views import BookListView

urlpatterns = [
    path('books/', BookListView.as_view(), name='book-list'),
]

Тепер у Swagger UI:

1. Знайдіть ендпоінт /books/ (метод GET).
2. Натисніть "Try it out", потім "Execute".
3. Внизу ви побачите:
   • Request URL: Вказує згенерований URL вашого запиту.
   • Response Body: Тіло відповіді, наприклад:

     [
       {"id": 1, "title": "1984", "author": "George Orwell"},
       {"id": 2, "title": "To Kill a Mockingbird", "author": "Harper Lee"}
     ]
     

   • Response Code: Очікуваний "200 OK".

Відправка запитів з параметрами

Тепер давайте протестуємо ендпоінт з параметрами. Наприклад, ендпоінт, який повертає книгу за її ID.

Приклад коду ендпоінта:

# views.py
class BookDetailView(APIView):
    def get(self, request, book_id):
        books = {
            1: {"id": 1, "title": "1984", "author": "George Orwell"},
            2: {"id": 2, "title": "To Kill a Mockingbird", "author": "Harper Lee"}
        }
        book = books.get(book_id, {"error": "Book not found"})
        return Response(book)

Додайте маршрут:

path('books/<int:book_id>/', BookDetailView.as_view(), name='book-detail'),

Тепер у Swagger UI:

1. Знайдіть ендпоінт /books/{book_id}/.
2. Натисніть "Try it out".
3. Введіть будь-яке book_id, наприклад 1, і натисніть "Execute".
4. Переконайтеся, що ви отримуєте правильну відповідь, наприклад:

   {"id": 1, "title": "1984", "author": "George Orwell"}
   

Redoc: тестування та переваги

Якщо Swagger UI — це інтерактивний інструмент для вивчення та тестування API, то Redoc більше підходить для створення красивої та статичної документації. Але це не означає, що через Redoc не можна проводити тести!

Redoc підтримує:

• Зрозумілу документацію з красивим UI;
• Вкладені структури даних;
• Легке налаштування рівнів деталізації для кінцевих користувачів;
• Можливості для тестування API аналогічно Swagger.

Перейдіть на URL Redoc вашого додатка, наприклад, http://127.0.0.1:8000/redoc/. Як і в Swagger UI, оберіть потрібний ендпоінт, ознайомтеся з параметрами та спробуйте відправити запити.

Порівняння Swagger і Redoc

На перший погляд Swagger і Redoc надають схожі функції, але:

Практичне заняття

Тепер ви налаштуєте Swagger і Redoc для тестування свого API. Ось план:

1. Знайдіть у вашому проєкті ендпоінти, які повертають дані (GET-запити).
2. Налаштуйте параметри ендпоінтів через drf-yasg (анотації дозволяють описувати вхідні дані та відповіді).
3. Використовуйте Swagger UI, щоб:
   • Запитувати ресурси через GET, POST або інші методи;
   • Перевіряти відповіді з різними параметрами.
4. Перемкніться на Redoc і оцініть, наскільки документація "читабельна".
5. Спробуйте самостійно додати анотацію для специфічного ендпоінта, наприклад описати можливі помилки (код 404 або 400).

Типові помилки при роботі з документацією

Часто зустрічаються проблеми:

• Невідповідність документації і API: завжди перевіряйте, щоб документація збігалася з поточними версіями ендпоінтів.
• Неописані параметри: додайте анотації для обов'язкових і необов'язкових параметрів.
• Помилка типізації: наприклад, вказання параметра як integer, тоді як API очікує рядок.
• Надмірне використання POST: багато хто починає використовувати POST для всього, забуваючи про правильні методи (привіт REST!).

Тепер, озброєні Swagger і Redoc, ви можете не тільки створити ідеальну документацію, але й перевірити всі свої ендпоінти без зайвих перемикань між інструментами. А ще, бонусом, ваші колеги та майбутні співбесіди оцінять такий професіоналізм. Ну хто тепер король/королева документування? 👑