Для чего нужен Swagger?

Swagger: Полное объяснение

Swagger (теперь официально OpenAPI Specification) — это стандарт для описания и документирования REST API. Для QA-инженера Swagger — это мощный инструмент, который помогает понять API, генерировать тесты и обнаруживать несоответствия между документацией и реальной реализацией.

История переименования

Swagger → OpenAPI Specification (OAS)

• Swagger 2.0 (2015) — был популярным стандартом
• OpenAPI 3.0 (2017) — переименование, значительное улучшение
• OpenAPI 3.1 (2021) — текущий стандарт

Сейчас термин "Swagger" часто используется для обозначения инструментов (Swagger UI, Swagger Editor), а "OpenAPI" — для спецификации.

Основная идея

Swagger позволяет описать API в структурированном YAML или JSON формате, который могут читать и люди, и машины.

Без Swagger: разработчик вручную пишет документацию на markdown, которая может устаревать и расходиться с реальным кодом.

С Swagger: спецификация генерируется из кода или наоборот, и всегда синхронизирована с реальностью.

Структура Swagger спецификации

Минимальный пример:

openapi: 3.0.0
info:
  title: Мой API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Получить список пользователей
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

Ключевые секции:

1. openapi — версия спецификации (3.0.0, 3.1.0)
2. info — метаинформация (название, описание, версия)
3. servers — список базовых URL сервера
4. paths — описание всех эндпоинтов API
5. components — переиспользуемые схемы (модели данных)
6. security — схемы аутентификации

Описание эндпоинтов

Полный пример эндпоинта:

paths:
  /users/{id}:
    get:
      summary: Получить пользователя по ID
      description: Возвращает информацию о конкретном пользователе
      parameters:
        - name: id
          in: path
          required: true
          description: ID пользователя
          schema:
            type: integer
      responses:
        '200':
          description: Пользователь найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Пользователь не найден
        '401':
          description: Не авторизован
    put:
      summary: Обновить пользователя
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: Успешно обновлено
        '400':
          description: Неверные данные

Элементы эндпоинта:

• parameters — параметры пути, query, header, cookie
• requestBody — тело запроса с описанием схемы
• responses — возможные ответы и их коды

Swagger UI — интерактивная документация

Swagger UI автоматически генерирует красивый интерфейс для просмотра API.

Возможности:

• Просмотр всех эндпоинтов
• Описание параметров каждого эндпоинта
• Пробные запросы ("Try it out")
• Просмотр примеров ответов
• Скачивание спецификации

Типичный URL: https://api.example.com/docs или https://api.example.com/swagger-ui

Практическое применение в QA

1. Изучение API

Вместо того, чтобы просить разработчика объяснить API, QA открывает Swagger UI и видит:

• Все эндпоинты
• Параметры и их типы
• Коды ошибок
• Примеры запросов и ответов

2. Генерация тест-кейсов

Из Swagger можно автоматически генерировать тесты:

• Для каждого параметра — тесты с валидными и невалидными значениями
• Для каждого статус-кода — проверить, что он возвращается в нужных случаях
• Coverage анализ — какие эндпоинты протестированы

Инструменты: Swagger Codegen, REST Assured, Postman (импорт Swagger).

3. Pairwise Testing с Swagger

Если эндпоинт имеет множество параметров, Swagger помогает:

• Увидеть все параметры и их типы
• Применить попарное тестирование
• Генерировать минимальный набор тестов для полного покрытия

Пример:

/search:
  get:
    parameters:
      - name: category
        schema:
          enum: [electronics, books, clothing]  # 3 значения
      - name: sort
        schema:
          enum: [price_asc, price_desc, rating]  # 3 значения
      - name: page
        schema:
          type: integer
          minimum: 1  # Граничное значение!

Для полного покрытия нужно ~6 тестов (попарное тестирование), а не 3×3×∞.

4. Проверка соответствия документации коду

Сценарий: Swagger говорит, что параметр age обязателен (required: true), но код его не проверяет.

Как найти: отправить запрос БЕЗ параметра age:

• По Swagger: должна быть ошибка 400
• На самом деле: запрос прошёл без ошибки → баг документации или кода

5. Граничные значения из Swagger

parameters:
  - name: age
    schema:
      type: integer
      minimum: 18
      maximum: 100

Тесты граничных значений:

• 17 (< minimum) → ошибка 400
• 18 (= minimum) → успех
• 100 (= maximum) → успех
• 101 (> maximum) → ошибка 400

Импорт Swagger в тестовые фреймворки

Postman

1. File → Import → URL
2. Вставить URL спецификации: https://api.example.com/swagger.json
3. Postman создаст коллекцию со всеми эндпоинтами
4. Добавить тесты и переменные
5. Запустить автоматически

REST Assured (Java)

import io.restassured.RestAssured;
import org.junit.Test;

public class ApiTest {
    @Test
    public void testGetUser() {
        RestAssured
            .given()
              .baseUri("https://api.example.com/v1")
              .get("/users/123")
            .then()
              .statusCode(200)
              .body("name", notNullValue());
    }
}

Pytest с Swagger

import requests

def test_get_users():
    response = requests.get("https://api.example.com/v1/users")
    assert response.status_code == 200
    assert isinstance(response.json(), list)

Типичные проблемы, которые выявляет Swagger

Проблема 1: Missing required parameter

# Swagger говорит:
parameters:
  - name: user_id
    required: true

# Но разработчик забыл проверить в коде
# QA отправляет запрос БЕЗ user_id → неожиданный результат

Проблема 2: Wrong status code

# Swagger обещает:
responses:
  '404':
    description: User not found

# Реально возвращается:
  '200' с пустым телом

Проблема 3: Schema mismatch

# Swagger описывает:
response_schema:
  properties:
    id:
      type: integer
    name:
      type: string

# Реально возвращается:
  {"id": "123", "name": 456}  # Типы поменялись!

Инструменты для работы со Swagger

Для создания/редактирования:

• Swagger Editor (editor.swagger.io)
• Visual Studio Code + OpenAPI extension
• Jetbrains IDE (встроенная поддержка)

Для просмотра:

• Swagger UI (встроенная в приложение)
• Swagger Inspector (облачное решение)

Для тестирования:

• Postman
• REST Assured
• Dredd (для BDD тестирования API)
• Schemathesis (автоматическое генерирование тестов)

Лучшие практики

1. Всегда документируй status codes — не забывай про 401, 403, 404, 500
2. Используй примеры — добавляй примеры запросов и ответов
3. Типизируй параметры — указывай minimum, maximum, enum, pattern
4. Версионируй API — в пути /v1/, /v2/
5. Содержи в актуале — спецификация должна матчить коду
6. Используй схемы — переиспользуй $ref для моделей

Заключение

Swagger для QA — это не просто красивая документация, а:

• Источник истины о структуре API
• Инструмент генерирования тестов для полного покрытия
• Способ выявления несоответствий между docs и реальностью
• Ускоритель разработки тестов через импорт в инструменты

При отсутствии актуальной Swagger документации — это первый красный флаг для QA-инженера, что с проектом что-то не так.