Как выполнить запрос в Swagger

Отличный вопрос! Работа с Swagger (ныне чаще называемым OpenAPI Specification) — это базовый навык для тестирования REST API. Выполнить запрос можно несколькими способами, в зависимости от того, используете ли вы интерактивную веб-документацию (Swagger UI) или инструменты командной строки. Я подробно разберу оба подхода.

1. Выполнение запроса через Swagger UI (Интерактивный веб-интерфейс)

Это самый распространенный и наглядный способ. Swagger UI автоматически генерируется из OpenAPI-спецификации.

Пошаговый алгоритм:

1. Навигация к конечной точке (endpoint): Откройте веб-страницу с документацией (например, https://api.example.com/docs). Вы увидите список всех доступных API-методов, сгруппированных по тегам (например, User, Order). Разверните интересующий вас метод, кликнув на него.

2. Параметры запроса:

    *   **Path parameters:** Параметры, встроенные в URL (например, `/users/{id}`). Нужно заполнить поле `id`.
    *   **Query parameters:** Параметры, добавляемые после `?` в URL (например, `?limit=10&active=true`). Обычно представлены в виде полей для ввода.
    *   **Body:** Для методов `POST`, `PUT`, `PATCH`. Здесь вы указываете тело запроса в формате JSON (или другом, поддерживаемом API). Swagger UI часто предоставляет пример (example value), который можно отредактировать.
    *   **Headers:** Заголовки запроса, такие как `Authorization: Bearer <token>` или `Content-Type`. Обязательные заголовки часто уже подставлены.

1. Авторизация (если требуется): Найдите кнопку "Authorize" (обычно вверху страницы). В появившемся окне введите свои учетные данные (например, API-ключ, токен OAuth 2.0, данные для Basic Auth). После этого Swagger UI будет автоматически подставлять этот токен во все запросы.

2. Выполнение запроса: Нажмите кнопку "Try it out". После этого поля для ввода параметров станут активными. Заполните их и нажмите кнопку "Execute".

3. Анализ ответа (Response): После выполнения запроса в интерфейсе отобразятся:

    *   **Curl:** Сгенерированная команда `curl` для этого запроса. Очень полезно для воспроизведения запроса вне браузера.
    *   **Request URL:** Финальный URL, который был отправлен на сервер.
    *   **Server Response:**
        *   **Код статуса** (например, `200 OK`, `404 Not Found`).
        *   **Тело ответа (Response body)** в формате JSON/XML.
        *   **Заголовки ответа (Response headers).**

Пример работы в Swagger UI: Допустим, мы тестируем эндпоинт GET /users/{userId}/orders.

// 1. После нажатия "Try it out" вводим параметры:
// Path parameter: userId = 123
// Query parameter: status = "shipped"

// 2. Нажимаем "Execute". В ответе видим:

Response Code: 200
Response Body:
[
  {
    "orderId": 456,
    "status": "shipped",
    "total": 99.99
  }
]

// 3. А также сгенерированный Curl:
curl -X GET "https://api.example.com/users/123/orders?status=shipped" \
  -H "Authorization: Bearer your_token_here"

2. Выполнение запроса через cURL (командная строка)

Swagger UI генерирует готовую команду curl для каждого выполненного запроса. Это мощный инструмент для автоматизации проверок, интеграции в скрипты и CI/CD пайплайны.

• Базовый GET-запрос:

  curl -X GET "https://api.example.com/api/v1/users"
  

• Запрос с заголовками и телом (POST):

  curl -X POST "https://api.example.com/api/v1/users" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLC..." \
    -d '{"name": "John Doe", "email": "john@example.com"}'
  

    *   `-X`: Метод запроса.
    *   `-H`: Заголовок (может быть несколько).
    *   `-d`: Тело запроса (data).

• Сохранение ответа в файл и вывод заголовков (полезно для отладки):

  curl -i -X GET "https://api.example.com/api/v1/items" \
    -o response.json
  

    *   `-i`: Показывает заголовки ответа в выводе.
    *   `-o`: Сохраняет тело ответа в указанный файл.

3. Практические советы для QA-инженера

• Тестирование валидации: Пробуйте отправлять невалидные данные: строки вместо чисел в path/query параметрах, некорректный JSON в body, отрицательные значения, пустые строки, значения на границах (boundary values).
• Проверка кодов ответа: Осознанно тестируйте не только 200 OK, но и ошибки: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Server Error. Для этого можно модифицировать запросы в Swagger UI или curl.
• Использование переменных окружения: В curl или при использовании инструментов вроде Postman/Insomnia, выносите базовый URL и токены в переменные. Это делает тесты переносимыми.
• Автоматизация: Для регрессионного тестирования API используйте фреймворки: pytest + requests (Python), REST Assured (Java), Supertest (Node.js). Swagger UI и сгенерированные curl команды — отличная стартовая точка для написания таких автотестов.

  # Пример на Python с использованием библиотеки requests
  import requests
  
  BASE_URL = "https://api.example.com"
  headers = {"Authorization": "Bearer token123"}
  
  # Тест GET-запроса
  response = requests.get(f"{BASE_URL}/users/123", headers=headers)
  assert response.status_code == 200
  assert response.json()["id"] == 123
  
  # Тест POST-запроса
  new_user = {"name": "Alice"}
  response = requests.post(f"{BASE_URL}/users", json=new_user, headers=headers)
  assert response.status_code == 201
  

Резюме: Swagger UI — это интерактивный "песочница" для первоначального изучения и ручного тестирования API. Сгенерированная им команда curl — это мост к автоматизации. Эффективный QA-инженер должен уверенно пользоваться обоими методами, чтобы быстро проводить исследовательское тестирование и создавать стабильные автоматизированные проверки. Всегда обращайте внимание не только на "счастливый путь", но и на корректность описания ошибок, заголовки, время ответа и соответствие документации реальному поведению системы.