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

{
  "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. Шаблони без значень комітяться в репозиторій, файли з секретами — ні. Для роботи з чутливими даними використовуйте змінні CI-системи, а не зберігайте їх у колекції.

Pre-request скрипти та автотести

Pre-request скрипти виконуються перед кожним запитом. Приклад — автоматичне оновлення токена:

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);
    });
}

Такий скрипт гарантує, що токен завжди актуальний — навіть при тривалих сесіях тестування.

Які помилки допускають при створенні Postman Collection?

• Відсутність змінних оточення — ви будете змінювати URL у кожному запиті.
• Немає pre-request скриптів для оновлення токена — тести впадуть після завершення сесії.
• Тести перевіряють лише статус-код — додайте перевірку JSON-схеми за допомогою pm.response.to.have.jsonSchema.
• Колекція не версіонується — зберігайте її в Git разом з кодом.
• Не налаштований Newman у CI — тести не запускаються автоматично після деплою.

Що входить у документування API під ключ?

Ми надаємо:

• Готову Postman Collection (структура, змінні, приклади відповідей).
• Environments для всіх оточень (dev/staging/production).
• Набір автотестів з перевіркою статусів та схем відповідей.
• Pre-request скрипти для автоматичної аутентифікації.
• Інтеграцію з CI через Newman (GitHub Actions, GitLab CI).
• Публікацію документації на Postman API Network.
• Навчання команди роботі з колекцією.

Замовте розробку Postman Collection і отримайте актуальну документацію з автотестами.

Порівняння Postman Collection та OpenAPI

Postman Collection краще підходить для швидкого тестування та налагодження, особливо в командній роботі. Проте OpenAPI корисний для генерації клієнтів та серверів.

Процес роботи та терміни

Терміни: базова колекція (20–30 ендпоінтів) — 1–2 дні. З інтеграцією та публікацією — 1 додатковий день. Точні терміни розраховуємо після аудиту.

Покрокова інструкція з налаштування Newman у CI

1. Встановіть Newman глобально: npm install -g newman.
2. Створіть файл newman-run.js з командами для запуску.
3. У CI-конфізі (GitHub Actions) додайте крок:

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

4. Для отримання звітів використовуйте --reporters cli,json.
5. Заплануйте прогін після кожного деплою.

--bail failure зупиняє прогін при першій помилці — зручно для smoke-тестів після деплою.

Чому варто обрати нас?

Більше 10 років досвіду в розробці API та 50+ проєктів із документування. Гарантуємо актуальність колекції та готовність до використання одразу після передачі. Інвестиції в створення Postman Collection окупаються: середня економія бюджету на тестування становить 30%. Отримайте консультацію щодо вашого API — зв'яжіться з нами.