Разработчик тратит до 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 — свяжитесь с нами.