Зачем тестировать документацию 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 codeDocs говорят 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.

Результаты

  1. Отчёт валидации спецификации.
  2. Таблица аудита полноты.
  3. Отчёт обнаружения drift-а.
  4. Таблица сравнения документации ошибок.
  5. Код автоматизированного набора тестов.