Документация API — это описание всех endpoint-ов, методов, параметров, форматов запросов и ответов, а также ошибок. Без документации тестировщик не знает, что ожидать от API.
Зачем документация тестировщику:
Понять, какие endpoint-ы существуют
Узнать, какие параметры обязательные/опциональные
Определить ожидаемые статус-коды и формат ответов
Составить тест-кейсы на основе спецификации
Сравнить поведение API с документацией
Что такое OpenAPI Specification (OAS)?
OpenAPI Specification (бывший Swagger Specification) — стандарт для описания REST API в формате YAML или JSON. Позволяет описать весь API в одном файле.
OpenAPI-спецификация — готовый источник для составления тест-кейсов. Вот систематический подход:
Шаг 1: Список всех endpoint-ов
Пройдите по paths и составьте список:
Endpoint
Метод
Описание
/users
GET
Список пользователей
/users
POST
Создать пользователя
/users/{id}
GET
Получить пользователя
/users/{id}
PUT
Обновить пользователя
/users/{id}
PATCH
Частичное обновление
/users/{id}
DELETE
Удалить пользователя
Шаг 2: Тест-кейсы для каждого endpoint-а
Из спецификации извлекаем:
Для POST /users (requestBody + responses):
Позитивные тесты:
Отправить все обязательные поля → 201
Отправить все обязательные + опциональные поля → 201
Проверить, что ответ содержит все поля из схемы User
Негативные тесты (из required и type):
4. Без обязательного поля name → 400/422
5. Без обязательного поля email → 400/422
6. name — пустая строка (нарушает minLength: 1) → 422
7. name — строка из 256 символов (нарушает maxLength: 255) → 422
8. email — не формат email → 422
9. role — значение не из enum → 422
10. Дублирующийся email → 409
11. Пустое тело → 400
12. Невалидный JSON → 400
Тесты авторизации:
13. Без токена → 401
14. С невалидным токеном → 401
15. Без прав на создание → 403
Для GET /users/{id} (parameters + responses):
Позитивные:
Существующий ID → 200 + данные пользователя
Проверить все поля в ответе
Негативные:
3. Несуществующий ID → 404
4. ID = 0 → 400/404
5. ID = -1 → 400/404
6. ID = "abc" (строка вместо числа) → 400
7. Без авторизации → 401
Шаг 3: Проверка из схем (components/schemas)
Для каждого поля в схеме проверяем граничные значения:
# Из спецификации:
name:
type: string
minLength: 1
maxLength: 255
# Тест-кейсы:
# ✓ "" → 422 (нарушает minLength)
# ✓ "A" → 200 (граница minLength)
# ✓ строка из 255 символов → 200 (граница maxLength)
# ✓ строка из 256 символов → 422 (нарушает maxLength)
# ✓ null → 400/422
Шаг 4: Проверка зависимостей между endpoint-ами
Составьте бизнес-сценарии:
1. POST /users → создать → получить id
2. GET /users/{id} → проверить, что создан
3. PATCH /users/{id} → обновить имя
4. GET /users/{id} → проверить, что имя обновлено
5. DELETE /users/{id} → удалить
6. GET /users/{id} → 404