Розробник витрачає до 3 годин на день на перевірку ендпоінтів за застарілою документацією. Postman (software) Collection скорочує цей час до 15 хвилин. Ми створили колекцію для проєкту з 200+ ендпоінтами: після впровадження кількість багів у релізі зменшилася на 40%. Наш досвід — 10+ років розробки та 50+ проєктів із документування API. Середня економія бюджету на тестування — 30%, окупність інвестицій — менше 3 місяців. Отримайте консультацію щодо вашого API — зв'яжіться з нами.
Як Postman Collection вирішує проблему актуальної документації?
Неактуальна документація — часта біль: ендпоінти змінюються, параметри застарівають, а розробники витрачають години на налагодження. Postman Collection — це живий документ: ви одразу виконуєте запити, бачите реальні відповіді та автоматично перевіряєте статуси. Ми гарантуємо, що після передачі колекція відповідатиме API — використовуємо автотести, які валідують кожен ендпоінт. Колекція — це набір збережених запитів, організованих у папки.
Структура та ключові елементи — документування API Postman
Приклад структури колекції
{
"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 |
|---|---|---|
| Мета | Ручне тестування та виконання запитів | Опис структури API |
| Формат | JSON (Collection v2.1) | YAML/JSON (OpenAPI 3.0) |
| Тестування | Вбудовані тести pm.test |
Вимагає зовнішніх інструментів |
| CI/CD | Newman | Парсери (Swagger, Prism) |
| Документація | Інтерактивна, з можливістю відправлення запитів | Статична, для читання |
Postman Collection краще підходить для швидкого тестування та налагодження, особливо в командній роботі. Проте OpenAPI корисний для генерації клієнтів та серверів.
Процес роботи та терміни
| Етап | Тривалість |
|---|---|
| Аудит API — вивчення ендпоінтів, типів відповідей, схем аутентифікації | 0.5 дня |
| Проектування колекції — групування запитів, визначення змінних та тестів | 0.5 дня |
| Створення — написання структури, pre-request скриптів, тестів | 1 день на 20–30 ендпоінтів |
| Тестування — прогін колекції, виправлення помилок | 0.5 дня |
| Інтеграція — налаштування Newman у CI, публікація документації | 1 день |
Терміни: базова колекція (20–30 ендпоінтів) — 1–2 дні. З інтеграцією та публікацією — 1 додатковий день. Точні терміни розраховуємо після аудиту.
Покрокова інструкція з налаштування Newman у CI
- Встановіть Newman глобально:
npm install -g newman. - Створіть файл
newman-run.jsз командами для запуску. - У CI-конфізі (GitHub Actions) додайте крок:
- name: Run API Tests
run: |
newman run collection.json \
--environment env.ci.json \
--bail failure
- Для отримання звітів використовуйте
--reporters cli,json. - Заплануйте прогін після кожного деплою.
--bail failure зупиняє прогін при першій помилці — зручно для smoke-тестів після деплою.
Чому варто обрати нас?
Більше 10 років досвіду в розробці API та 50+ проєктів із документування. Гарантуємо актуальність колекції та готовність до використання одразу після передачі. Інвестиції в створення Postman Collection окупаються: середня економія бюджету на тестування становить 30%. Отримайте консультацію щодо вашого API — зв'яжіться з нами.