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

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

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

Структура колекції

{
  "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.

Оточення — Різні середовища

{
  "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 через випадаючий список. Файли з секретами не фіксуються в репозиторії (.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 додатковий день.