Документирование API (Postman Collection) для веб-приложения

Документирование API (Postman Collection) для веб-приложения

Postman Collection — формат JSON/YAML (Collection v2.1), описывающий HTTP-запросы, переменные окружения, тесты и примеры ответов. В отличие от OpenAPI, ориентирован на ручное тестирование и совместную работу команды, а не на генерацию документации. Публикуется на Postman API Network или экспортируется в виде файла для onboarding новых разработчиков.

Структура коллекции

{
  "info": {
    "name": "MyApp API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url", "value": "https://api.example.com/v1" },
    { "key": "token", "value": "" }
  ],
  "item": [
    {
      "name": "Auth",
      "item": [
        {
          "name": "Login",
          "request": {
            "method": "POST",
            "url": "{{base_url}}/auth/login",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\"email\": \"[email protected]\", \"password\": \"secret\"}"
            }
          },
          "event": [{
            "listen": "test",
            "script": {
              "exec": [
                "pm.test('Status 200', () => pm.response.to.have.status(200));",
                "const json = pm.response.json();",
                "pm.collectionVariables.set('token', json.data.token);"
              ]
            }
          }]
        }
      ]
    }
  ]
}

pm.collectionVariables.set — ключевой паттерн: тест логина автоматически сохраняет токен, все следующие запросы используют {{token}} в заголовке Authorization.

Environments — разные окружения

{
  "name": "Production",
  "values": [
    { "key": "base_url", "value": "https://api.example.com/v1", "enabled": true },
    { "key": "token", "value": "", "enabled": true }
  ]
}

Отдельные файлы env.development.json, env.staging.json, env.production.json — переключаются в Postman через dropdown. Файлы с секретами не коммитятся в репозиторий (.gitignore), шаблоны без значений — коммитятся.

Pre-request Scripts

// Автоматическое обновление токена перед каждым запросом
const tokenExpiry = pm.collectionVariables.get('token_expiry');
if (!tokenExpiry || Date.now() > parseInt(tokenExpiry)) {
    pm.sendRequest({
        url: pm.variables.get('base_url') + '/auth/refresh',
        method: 'POST',
        header: { 'Content-Type': 'application/json' },
        body: {
            mode: 'raw',
            raw: JSON.stringify({ refresh_token: pm.collectionVariables.get('refresh_token') })
        }
    }, (err, res) => {
        pm.collectionVariables.set('token', res.json().data.access_token);
        pm.collectionVariables.set('token_expiry', Date.now() + 3600000);
    });
}

Генерация из OpenAPI

# Импорт openapi.yaml в коллекцию через Postman CLI
postman collection convert openapi.yaml --output collection.json

# Или через API
curl -X POST https://api.getpostman.com/collections \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -d @collection.json

Обратно: из Collection можно экспортировать в OpenAPI через Postman UI (Export → OpenAPI 3.0).

Newman — запуск в CI

npm install -g newman

newman run collection.json \
  --environment env.staging.json \
  --reporters cli,junit \
  --reporter-junit-export results/newman.xml

Интеграция с GitHub Actions:

- name: Run API Tests
  run: |
    newman run collection.json \
      --environment env.ci.json \
      --bail failure

--bail failure останавливает прогон при первой ошибке — удобно для smoke-тестов после деплоя.

Публикация документации

Postman позволяет публиковать коллекцию как интерактивную документацию на <team>.postman.co/docs. Авто-обновление через Postman API:

curl -X PUT "https://api.getpostman.com/collections/$COLLECTION_ID" \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -d @collection.json

Сроки

Создание коллекции для API (20–30 эндпоинтов, переменные окружения, тесты с авто-сохранением токена): 1–2 дня. С Newman в CI, pre-request скриптами, публикацией документации: 1 день дополнительно.