Использование 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, вы можете не только создать идеальную документацию, но и проверить все свои эндпоинты без лишних переключений между инструментами. А ещё, бонусом, ваши коллеги и будущие собеседования оценят такой профессионализм. Ну кто теперь царь/царица документирования? 👑

1

Задача

Модуль 3: Django, 23 уровень, 8 лекция

Недоступна

Настройка Redoc для вашего проекта

Настройка Redoc для вашего проекта

Открыть

1

Задача

Модуль 3: Django, 23 уровень, 8 лекция

Недоступна

Добавление Query параметры и тестирование

Добавление Query параметры и тестирование

Открыть