О чём речь
Apidog позиционирует себя как универсальная платформа для работы с API: проектирование, тестирование, mock-сервер, документация. Всё в одном флаконе. Звучит как маркетинг, но интерфейс выглядел приятно, в общем решил сам проверить на практике.
Пройдём полный цикл: от создания проекта до запуска тестов. Со скриншотами и личными впечатлениями.
Быстрый старт: пять минут до первого теста
Регистрация заняла секунд тридцать. Заходим на apidog.com, нажимаем "Get Started Free", выбираем вход через GitHub (есть ещё Google и email). Два клика, подтверждение доступа к аккаунту GitHub, и мы внутри. Никаких подтверждений почты в три этапа, никаких обязательных опросов "расскажите о вашей команде".
Есть web-версия и desktop-приложение для Windows, Mac, Linux. Desktop можно скачать тут же с главной страницы. Я использовал web, разницы в функционале не заметил.
После входа видим экран создания проекта:
Четыре варианта на выбор:
Create blank project создаёт пустой проект. Появится окно с полями Name (обязательное) и Description (опциональное). После создания получаем чистое рабочее пространство с пустым деревом API слева.
Create sample project (Pet Store) разворачивает готовый шаблон классического Petstore API. Это тот самый пример из спецификации OpenAPI, который используют все туториалы. Внутри уже есть эндпоинты, схемы данных, примеры запросов. Классика обучения.
Import OpenAPI Spec (помечен как Recommended) позволяет загрузить существующую спецификацию. Поддерживаются форматы OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0. Можно загрузить файл (JSON или YAML), вставить URL на спецификацию, или скопировать содержимое в текстовое поле. После импорта Apidog автоматически создаст все эндпоинты, схемы и примеры из спецификации.
Import Postman collection для миграции из Postman. Экспортируете коллекцию из Postman в формате JSON (Collection v2.1), загружаете сюда. Переменные окружения импортируются отдельным файлом. Тесты на JavaScript из Postman частично конвертируются в формат Apidog, но сложные скрипты придётся переписывать вручную. С этим особо не игрался, пока не могу ничего внятного рассказать.
Для знакомства с инструментом выбираем Pet Store. Нажимаем на карточку, проект создаётся мгновенно, и мы попадаем в основной интерфейс.
Структура проекта: первое отличие от Postman
После создания Pet Store открывается основной интерфейс:
Левая панель содержит дерево API. В корне видим Store API, внутри папка Endpoints с группами: Pet (6 эндпоинтов), Store (5), User (6). Отдельно вынесены Websocket и Socket.IO (9 операций). Да, такие протоколы тоже поддерживаются из коробки, не нужно ставить отдельные плагины.
Каждая группа раскрывается кликом. Внутри Pet видим: GET Get a pet, PUT Update a pet, DEL Delete a pet, POST Create a pet, GET List pets, POST Upload a pet image. Цветовая маркировка по HTTP-методам стандартная: GET зелёный, POST жёлтый, PUT синий, DELETE красный.
Ниже дерева API расположены дополнительные разделы:
Schemas содержит схемы данных. Для Pet Store это Pet, Category, Tag, Order, User и другие. Схемы переиспользуются в эндпоинтах: указываете ссылку на схему вместо копирования структуры в каждый запрос. Изменили схему в одном месте, обновилось везде.
Components хранит переиспользуемые компоненты: параметры запросов, заголовки, примеры ответов. Если у вас во всех эндпоинтах есть параметр Авторизация, создаёте его один раз в компонентах и ссылаетесь на него.
Quick Requests для быстрых одноразовых запросов без привязки к структуре API. Нужно проверить что-то на лету, не засоряя основное дерево. Аналог вкладки "New Request" в Postman.
Верхняя панель показывает текущую ветку (main), кнопки Install Browser Extension и Open on desktop. Браузерное расширение перехватывает запросы из DevTools и позволяет сразу импортировать их в проект. Тут тоже не углублялся, решил отдельно поизучать потом.
Центральная область пока пустая, предлагает создать New HTTP Endpoint, New Schema, New Markdown (для документации внутри проекта) или Quick Request.
Вот тут я заметил первое отличие от Postman. Здесь API-first подход. Структура проекта отражает структуру API: группы эндпоинтов, схемы данных, компоненты. В Postman я обычно накидываю запросы в коллекцию, потом пытаюсь разгрести этот хаос по папкам, потом понимаю что схемы живут отдельно в голове или в Swagger, а связи между ними нет. Здесь кто-то подумал о порядке до того, как я успел развести бардак.
Работа с эндпоинтом
Кликаем на GET Get a pet в дереве слева. Открывается интерфейс эндпоинта:
Верхняя строка показывает метод (GET) и путь (/pets/{id}). Справа кнопки Save и Send. Send выполняет запрос сразу, Save сохраняет изменения в проект.
Под строкой запроса расположены вкладки:
Request содержит всё для формирования запроса. Секция Params разделена на Query Params (параметры в URL после ?) и Path Params (параметры в пути, как {id}). Для Get a pet есть path-параметр id типа string с описанием "The unique identifier of the pet". Секции Body, Headers, Cookies, Auth позволяют настроить соответствующие части запроса. Pre Processors и Post Processors содержат действия до и после запроса.
Design переключает в режим документирования. Здесь редактируется описание эндпоинта, теги, примеры ответов для разных кодов.
Preview показывает как будет выглядеть документация для внешних пользователей.
Test Cases содержит тесты, привязанные к этому конкретному эндпоинту.
Mock настраивает mock-ответы.
В нижней части экрана область Response. Пока пустая с надписью "Click Send to get a response". После выполнения запроса здесь появится код ответа, заголовки, тело, время выполнения.
В Postman тесты и mock живут отдельно от запросов. Здесь всё рядом. Открыл эндпоинт и сразу видишь документацию, тесты, моки. Не нужно прыгать между вкладками и окнами.
Создание тестов: три клика вместо JavaScript
Переходим на вкладку Test Cases внутри эндпоинта Get a pet:
Интерфейс разделён на категории: All, Positive, Negative, Boundary, Security, Other. Это стандартные типы тестов. Positive для проверки что работает как ожидается. Negative для проверки обработки ошибок. Boundary для граничных значений. Security для проверки безопасности.
Справа кнопки "Generate with AI" и "+ Add Case". AI-генерация создаёт базовые тесты автоматически, но результат нужно проверять. Лучше создавать вручную.
Нажимаем "+ Add Case", выбираем категорию Positive, вводим название "Get existing pet successfully". Открывается редактор тест-кейса.
В редакторе сверху поле для названия и тегов. Ниже настройки запроса: метод GET уже выбран, путь /pets/{id} подставлен. В Path Params указываем значение id, например 1.
Теперь самое интересное: добавление проверок. Переходим в секцию Post Processors (вкладка справа от Settings). Нажимаем "+ Add" и выбираем Assertion.
Открывается окно настройки проверки:
Name задаёт название проверки, например "Check pet id exists".
Target Object определяет что проверяем. Варианты: Response JSON (тело ответа как JSON), Response Status (HTTP-код), Response Time (время ответа в мс), Response Headers (заголовки ответа), Response Raw (сырое тело).
JSONPath появляется при выборе Response JSON. Указываем путь к проверяемому полю. Для проверки наличия id пишем $.id. Для вложенных полей: $.data.user.name. Для элементов массива: $.items[0].id.
Condition задаёт условие. Доступные варианты: exists (поле существует), not exists, equals, not equals, contains, not contains, greater than, less than, matches regex, is null, is not null, is array, is object.
Для проверки наличия id в ответе настраиваем: Target Object = Response JSON, JSONPath = $.id, Condition = exists. Три клика, никакого кода.
Можно добавить несколько assertions в один тест. Например, проверить что id существует, что status равен "available", что name не пустой.
В Postman для этого пришлось бы писать:
pm.test("Check pet id exists", function () {
var jsonData = pm.response.json();
pm.expect(jsonData.id).to.exist;
});
pm.test("Check pet status is available", function () {
var jsonData = pm.response.json();
pm.expect(jsonData.status).to.eql("available");
});Для QA-инженера, который не хочет писать JavaScript на каждый чих, визуальный конструктор экономит время. Да, скриптами можно сделать больше. Но для 80% рутинных проверок хватает визуального конструктора.
Тестовые сценарии: полный CRUD за шесть шагов
Отдельные тесты хороши для проверки конкретных эндпоинтов. Но обычно нужен полный сценарий: создать сущность, получить её, обновить, удалить, проверить что удалилась.
В левой панели переходим из APIs в Tests (вторая иконка сверху). Открывается раздел Test Scenarios. В Pet Store уже есть готовый сценарий "Test CRUD pet":
Интерфейс сценария показывает список шагов в порядке выполнения:
POST Add a new pet to the store создаёт питомца. В теле запроса JSON с данными: name, status, category и т.д.
GET Get the pet info just added получает созданного питомца по id. Проверяет что питомец действительно создался.
PUT Update the pet info обновляет данные питомца. Меняет, например, status с "available" на "sold".
GET Validate the updation проверяет что обновление применилось. Ожидает новое значение status.
DELETE Deletes the pet удаляет питомца.
GET Validate the deletion проверяет что питомец удалён. Ожидает код 404.
Справа панель настроек сценария: Environment (выбор окружения), Test Data (внешние данные для параметризации), Iterations (количество повторов), Threads (параллельные потоки), Runs on (Local или Cloud).
Ключевой момент: как передать id созданного питомца в следующие шаги? Кликаем на первый шаг POST, переходим в Post Processors, нажимаем "+ Add" и выбираем "Extract Variable".
Настройки извлечения переменной:
Variable Name задаём pet_id.
Variable Scope выбираем Local Variables (доступна только в этом сценарии) или Environment Variables (доступна везде).
Source выбираем Response JSON.
JSONPath указываем $.id.
Теперь переменная pet_id автоматически заполнится значением из ответа первого шага.
В следующих шагах используем {{pet_id}} вместо захардкоженного значения. В Path Params шага GET вместо конкретного числа пишем {{pet_id}}. Переменная автоматически подставится из результата первого шага.
Можно добавлять свои шаги кнопкой "+ Add Step". Доступные типы: API Request (запрос к эндпоинту из проекта), Custom Request (произвольный запрос), Condition (ветвление по условию), Loop (цикл), Wait (пауза), Group (группировка шагов).
В Postman передача переменных делается через pm.environment.set() в скриптах:
var jsonData = pm.response.json();
pm.environment.set("pet_id", jsonData.id);Запуск тестов и результаты
В правой панели сценария нажимаем кнопку "Run". Появляется окно подтверждения с выбранными настройками: Environment, Iterations, Threads. Нажимаем "Run" ещё раз.
Открывается вкладка с результатами:
Верхняя часть показывает общую статистику:
Finished: 6 всего выполнено шагов.
Passed: 5 (83.33%) успешных.
Failed: 1 (16.67%) упавших.
Untested: 0 пропущенных.
Duration: 3.99s общее время выполнения.
Response Time: 3.35s суммарное время ответов сервера.
Average Response Time: 559ms среднее время одного ответа.
Assertions: Executed 2, Failed 1 статистика по проверкам.
Ниже детальный список шагов. Каждая строка содержит: статус (Passed/Failed), название шага, метод и путь, код ответа, время выполнения. Цветовая индикация: зелёный для успешных, красный для упавших.
Кликаем на упавший шаг "Validate the updation". Открывается детальная информация: полный запрос (URL, headers, body), полный ответ (status, headers, body), список assertions с указанием какая именно проверка не прошла и почему.
В правом верхнем углу кнопки "Run Again" (перезапуск), "Export Report" (экспорт в HTML/PDF), "Share" (поделиться ссылкой на отчёт).
Интерфейс отчёта приятнее, чем в Postman. Всё на одном экране, не нужно кликать по каждому тесту отдельно. Сразу видно где проблема.
Design Mode: документация из того же источника
Возвращаемся к эндпоинту Get a pet и переключаемся на вкладку Design:
Интерфейс меняется на редактор документации. Доступные поля:
Описание эндпоинта в формате Markdown. Можно добавить подробное описание логики, примеры использования, ограничения.
OperationId уникальный идентификатор операции для кодогенерации. Клиентские библиотеки используют его как имя метода. Для Get a pet это getPetById.
Maintainer ответственный за эндпоинт. Полезно в больших командах.
Tags для группировки в документации. Get a pet помечен тегом "pet".
Ниже секция Request с документацией параметров. Каждый параметр имеет поля: Name, Type (string, integer, boolean и т.д.), Example (пример значения), Description (описание).
Секция Responses содержит все возможные коды ответа. Для Get a pet это: 200 OK (успешный ответ с данными питомца), 400 BadRequest (неверный формат запроса), 401 Unauthorized (требуется авторизация), 403 Forbidden (доступ запрещён), 404 NotFound (питомец не найден), 429 TooManyRequests (превышен лимит запросов), 500 InternalServerError (ошибка сервера).
Для каждого кода ответа настраивается: описание, схема данных (ссылка на Schemas), примеры ответов.
Документация генерируется из того же источника, что и тесты. Добавили новый параметр в Request, он автоматически появится в документации. Изменили схему ответа, документация обновится. Нет рассинхрона между "что написано в Swagger" и "что реально работает".
Mock Server: фронтенд больше не ждёт бэкенд
Переключаемся на вкладку Mock внутри эндпоинта:
Верхняя часть показывает Mock URL. Два варианта: Local (http://127.0.0.1:порт) для локальной разработки и Cloud (https://xxx.apidog.io) для удалённого доступа. Cloud Mock нужно включить отдельно кнопкой "Enable Now".
Ниже секция Mock Expectations. Это правила: при каких условиях возвращать какой ответ. Каждое правило содержит:
Name название для понимания.
Condition условие срабатывания. Формат: "Path params id equal to X" или "Query params status equal to Y". Можно комбинировать несколько условий.
Creator кто создал правило.
Local/Cloud переключатели активации для локального и облачного mock.
Готовые правила в Pet Store:
Pet for sale: Path params id equal to 1. Возвращает питомца со статусом "available".
Pet sold: Path params id equal to 2. Возвращает питомца со статусом "sold".
Record not found: Path params id equal to 10000. Возвращает код 404 с сообщением об ошибке.
Invalid id format: Path params id equal to DDD. Возвращает код 400 с сообщением о неверном формате.
Кнопка "+ New Expectation" создаёт новое правило. В редакторе указываете условия, код ответа, заголовки и тело ответа.
Фронтенд может начинать работу сразу после согласования контракта API. Не нужно ждать пока бэкенд всё реализует. Mock-сервер поднимается автоматически. Не нужно ставить отдельные инструменты типа WireMock или json-server.
Публикация документации
В левой панели нажимаем иконку Publish Docs (четвёртая сверху). Открывается раздел публикации:
Левая часть содержит список сайтов документации. По умолчанию создан "Pet Store Main" со статусом Unpublished.
Правая часть показывает настройки публикации:
Publish Status текущий статус: Unpublished (черновик) или Published (опубликовано).
Release настройки версионирования. Source Branch выбирает ветку проекта (main по умолчанию). Environment задаёт базовый URL для примеров.
Basic Settings содержит Site Title (заголовок сайта в браузере и поисковиках), Site Icon (favicon).
Domain адрес опубликованной документации. Apidog provided domain выдаёт бесплатный адрес вида xxx.apidog.io. Можно подключить свой домен через Custom domain.
Нажимаем кнопку "Publish" в правом верхнем углу. Документация публикуется за несколько секунд.
На выходе интерактивный портал. Слева навигация по эндпоинтам, в центре документация выбранного эндпоинта, справа панель "Try it out" для выполнения запросов прямо из браузера. Примеры кода генерируются автоматически для разных языков: cURL, JavaScript, Python, Go, Java и других.
Можно отправить ссылку фронтендерам или внешним интеграторам. Они получат актуальную документацию с возможностью сразу попробовать запросы.
Сравнение с Postman: первые наблюдения
Несколько моментов, которые бросились в глаза.
Бесплатный Postman даёт 25 запусков коллекций в месяц. Apidog в бесплатной версии не считает запуски. Возможно, есть ограничения, которые я не нашёл за выходные, но пока выглядит щедро.
Mock-сервер здесь работает из коробки без дополнительных настроек. В Postman он тоже есть, но с ограничениями в бесплатной версии.
Визуальный конструктор assertions позволяет делать проверки без JavaScript. Для простых случаев удобно. Для сложных всё равно придётся писать код.
Design-first подход встроен в архитектуру. В Postman можно работать так же, но инструмент к этому не подталкивает.
Пока что
Однозначного вердикта "обязательно переходите и не пожалеете" у меня нет. Выходных мало для таких выводов.
Что могу сказать: тестировщикам в командах инструмент в целом нравится. Знакомый интерфейс, если работали с Postman. Логичные переходы между разделами. Интуитивно понятные сценарии использования. Не нужно объяснять где что находится, люди сами разбираются за полчаса.
Будем смотреть, как покажет себя при длительном использовании. Пока впечатления положительные, но это ещё не рекомендация.
Если кто-то уже использует Apidog на постоянной основе, расскажите в комментариях, какие подводные камни всплыли со временем.
