API Документация для Тестировщиков: Примеры Request/Response и Стратегии Тестирования

API документация для QA команд требует иного фокуса, чем документация для разработчиков. Тестировщикам нужны всесторонние примеры, сценарии ошибок, потоки аутентификации и крайние случаи—не только happy-path документация.

Основные Компоненты для QA-Ориентированной API Документации

1. Аутентификация и Авторизация

Документировать все методы auth с тестовыми учетными данными:

## Аутентификация

### Метод: Bearer Token (JWT)

**Получение Токена**:
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "test@example.com",
  "password": "Test123!"
}

Ответ:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Тестовые Учетные Записи

### 2. Примеры Request/Response для Всех Сценариев

**Случаи Успеха**:
```markdown
## Создать Заказ - Успех

**Request**:
```http
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "items": [
    {"product_id": 101, "quantity": 2}
  ],
  "shipping_address": {
    "street": "Главная ул. 123",
    "city": "Москва"
  }
}

Response: 201 Created:

{
  "id": 789,
  "status": "pending",
  "total": 129.99
}

Случаи Ошибок:

400 Bad Request - Некорректные Данные:

POST /api/v1/orders
{
  "items": []  // Пустой массив
}

Response:

{
  "error": "validation_error",
  "message": "Некорректные данные запроса",
  "details": [
    {"field": "items", "error": "должен содержать хотя бы один элемент"}
  ]
}

401 Unauthorized - Некорректный Токен:

{
  "error": "unauthorized",
  "message": "Некорректный или просроченный токен аутентификации"
}

403 Forbidden - Недостаточно Разрешений:

{
  "error": "forbidden",
  "message": "Недостаточно разрешений"
}

404 Not Found:

{
  "error": "not_found",
  "message": "Заказ с ID 99999 не найден"
}

3. Справочник Кодов Ошибок

## Коды Ошибок

| HTTP Код | Код Ошибки | Описание | Сценарий Тестирования |
|----------|-----------|----------|---------------------|
| 400 | validation_error | Провалена валидация данных | Отправить некорректные поля |
| 401 | unauthorized | Требуется аутентификация | Без токена, просроченный токен |
| 403 | forbidden | Недостаточно разрешений | Клиент пытается admin операцию |
| 404 | not_found | Ресурс не существует | Запросить несуществующий ID |
| 409 | conflict | Конфликт состояния | Дублирующееся создание |
| 429 | rate_limit_exceeded | Слишком много запросов | Превысить 1000 req/час |
| 500 | internal_server_error | Ошибка сервера | Тестировать с некорректным состоянием backend |

4. Postman Коллекция

Экспортировать коллекцию для тестировщиков:

{
  "info": {
    "name": "E-commerce API - QA Коллекция"
  },
  "item": [
    {
      "name": "Аутентификация",
      "item": [
        {
          "name": "Логин - Успех",
          "request": {
            "method": "POST",
            "url": "{{base_url}}/api/v1/auth/login"
          }
        }
      ]
    }
  ]
}

5. Лимиты Скорости

## Rate Limiting

**Лимиты**:
- Неаутентифицированные: 100 запросов/час
- Аутентифицированные пользователи: 1,000 запросов/час

**Тестирование Лимитов Скорости**:
```bash
for i in {1..1001}; do
  curl -H "Authorization: Bearer $TOKEN" \
    https://api.example.com/v1/products
done

Ожидаемое Поведение:

• Запрос 1-1000: 200 OK
• Запрос 1001: 429 Too Many Requests

### 6. Правила Валидации Данных

```markdown
## Валидация Полей

| Поле | Тип | Обязательное | Ограничения | Некорректные Примеры |
|------|-----|-------------|-------------|---------------------|
| name | string | Да | 1-200 символов | "", "a", (201 символ) |
| price | number | Да | > 0 | 0, -10 |
| category | string | Да | [electronics, clothing] | "invalid" |

7. Идемпотентность и Конкурентность

## Идемпотентность

**Идемпотентные Операции**:
- GET, PUT, DELETE

**Не Идемпотентные** (требуют ключи):
- POST /api/v1/orders

**Использование Ключей Идемпотентности**:
```http
POST /api/v1/orders
Idempotency-Key: unique-key-123

Тестирование Идемпотентности:

1. Отправить POST с ключом идемпотентности
2. Повторить идентичный запрос с тем же ключом
3. Ожидаемо: Второй запрос возвращает тот же результат

## Лучшие Практики

### 1. Явно Документировать Крайние Случаи

Не только показывать happy paths. Включать:
- Граничные значения
- Некорректные типы данных
- Отсутствующие обязательные поля

### 2. Предоставлять Примеры cURL

```bash
curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"product_id": 101}]}'

3. Включать Переменные Окружения

BASE_URL=https://staging.api.example.com
TEST_EMAIL=test@example.com

Заключение

Эффективная API документация для QA выходит за рамки описания эндпоинтов—она предоставляет полные сценарии тестирования, случаи ошибок, потоки аутентификации и правила валидации. Включая Postman коллекции, mock серверы и примеры крайних случаев, команды позволяют тестировщикам быстро создавать всесторонние тестовые наборы.