Зачем тестировать документацию API?
Документация API — это контракт с потребителями. Когда документация говорит, что GET /users возвращает JSON с name и email, потребители строят интеграции на этом обещании. Если API возвращает username вместо name, все интеграции ломаются.
Типы тестов документации
1. Валидность спецификации
Проверьте, что OpenAPI/Swagger спецификация валидна:
npx @redocly/cli lint openapi.yaml
2. Полнота документации
Проверьте, что каждый endpoint документирован с описаниями, параметрами, ответами, примерами и требованиями аутентификации.
3. Точность (обнаружение drift-а)
Самый ценный тест: проверить, что документация совпадает с реальным поведением API.
Используя Dredd:
npm install -g dredd
dredd openapi.yaml http://localhost:3000
Используя Schemathesis:
pip install schemathesis
schemathesis run http://localhost:3000/openapi.json --checks all
4. Валидация примеров
Проверьте, что документированные примеры работают, отправляя их в API.
Типичные баги документации
| Тип | Пример | Влияние |
|---|---|---|
| Неверный status code | Docs говорят 200, API возвращает 201 | Потребители проверяют неверный код |
| Отсутствующее поле | Docs показывают name, API возвращает username | Потребители получают undefined |
| Неверный тип | Docs говорят string, API возвращает number | Ошибки типов |
| Недокументированная ошибка | 422 не документирован | Потребители не обрабатывают ошибки валидации |
Автоматизация в CI
name: API Doc Testing
on: [push, pull_request]
jobs:
doc-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Валидация спецификации
run: npx @redocly/cli lint openapi.yaml
- name: Запуск Dredd
run: npx dredd openapi.yaml http://localhost:3000
Упражнение: Аудит документации API
Задание 1: Валидация спецификации
Провалидируйте OpenAPI spec, задокументируйте предупреждения и ошибки, исправьте и перевалидируйте.
Задание 2: Аудит полноты
Проверьте каждый endpoint: описание, параметры, ответы, примеры, аутентификация.
Задание 3: Обнаружение drift-а
Запустите Dredd или Schemathesis. Зафиксируйте расхождения. Категоризируйте каждое.
Задание 4: Документация ошибок
Вызовите каждое документированное условие ошибки. Сравните реальный ответ с документированным.
Задание 5: Автоматизированный набор тестов
Создайте набор тестов: валидация синтаксиса спецификации, отправка примеров, вызов документированных ошибок, запуск в CI.
Результаты
- Отчёт валидации спецификации.
- Таблица аудита полноты.
- Отчёт обнаружения drift-а.
- Таблица сравнения документации ошибок.
- Код автоматизированного набора тестов.