APItizer — конструктор REST API-контрактов

Добрый день, уважаемые читатели Хабра.

В этой статье я хочу рассказать о продукте APItizer, почему появилась потребность в его создании и какой путь привёл от небольшого Python-скрипта к полноценному инструменту для проектирования REST API-контрактов.

Если вам интересно сразу посмотреть на продукт, добро пожаловать в APItizer

(прямая ссылка, на случай поломки домена)

Несколько лет назад я перешёл в проект, в котором средний слой был реализован не классическим способом, а на основе собственной in-house разработки — «универсального среднего слоя».

У такого подхода было множество преимуществ, однако существовал и серьёзный недостаток: отсутствие явных моделей API. В результате не было серверной валидации типов и возможности автоматически формировать Swagger-документацию.

Хранение коллекции и её тестирование мы закрывали через Postman. При этом актуальность коллекции поддерживалась вручную, а тестирование занимало значительное время.

Поначалу процесс выглядел следующим образом:

• Коллекция Postman обновлялась вручную;

• Изменения фиксировались на общей странице в Confluence;

• После этого информация переносилась в отдельные документы с описанием API.

Со временем такой подход начал создавать всё больше проблем:

• Расхождение версий;

• Потеря актуальности данных;

• Большое количество ручной работы;

• Увеличение времени тестирования.

В какой-то момент стало понятно, что так дальше работать нельзя.

Попытка найти готовое решение

В это время ко мне на R&D попал APIDog.

После первого знакомства стало понятно, что инструмент решает практически все наши проблемы. Более того, нам даже не требовался весь объём его функциональности.

Однако на тот момент у продукта отсутствовал Enterprise-план, а значит, его нельзя было развернуть внутри инфраструктуры компании.

В итоге APIDog не был согласован: он отправился в технологический радар, а мы вернулись к существующему процессу. Именно тогда стало понятно, что необходимо создать собственное решение.

Какие цели нужно было решить

Я сформулировал четыре основные задачи:

• Создать единую точку правды.

• Синхронизировать коллекцию API для всей команды.

• Сократить время тестирования.

• Минимизировать количество ручных действий.

Для достижения этих целей были приняты следующие решения:

• Использовать подход Contract First;

• Хранить описание контракта в Confluence;

• Хранить коллекцию Postman в отдельном Git-репозитории;

• Автоматически генерировать схемы валидации;

• Автоматизировать обновление документации и коллекций.

Первый Python-скрипт

В тот момент я как раз изучал Python и решил использовать эту задачу как практический проект.

Через месяц появился первый MVP, и ещё около года ушло на доработку, рефакторинг и стабилизацию решения.

Что я получил в итоге

Появился полноценный Contract First и Test Driven процесс.

Процесс выглядел следующим образом:

• Аналитик описывает контракт в согласованной нотации на странице Confluence.

• Скрипт получает ID страницы.

• Скрипт:

  • Загружает страницу;

  • Извлекает описание метода;

  • Собирает JSON-запрос и ответ;

  • Генерирует JSON Schema для валидации;

  • Формирует Postman-тесты;

  • Обновляет коллекцию из Git;

  • Добавляет или обновляет API;

  • Публикует изменения обратно в репозиторий;

  • Обновляет страницу Confluence.

• Команда получает актуальную коллекцию и может сразу использовать её для тестирования.

В результате существенно сократилось время поддержки контрактов, повысилось качество документации, упростилось и ускорилось тестирование.

Почему этого оказалось недостаточно

Несмотря на успех решения, оставалась одна фундаментальная проблема.

Confluence всё ещё оставался точкой проектирования контракта.

По сути, мы использовали систему документации как инструмент проектирования.

Это работало, но не выглядело правильным архитектурным решением.

Для проектирования API должно существовать специализированное пространство, где пользователь работает непосредственно с контрактом, а документация является лишь производным артефактом.

Так появилась идея APItizer.

Важная оговорка. Скрипт, описанный выше, я писал сам, но как сотрудник компании и под её внутренние задачи. Это её внутренний инструмент: он принадлежит компании и остаётся внутри её контура.

APItizer не содержит и не переиспользует этот код. Это самостоятельный продукт, который мы с командой разрабатывали с нуля и за пределами организации. От корпоративного опыта он унаследовал понимание проблемы, подход Contract First и ясное представление о том, что нужно генерировать на выходе: документацию, коллекцию Postman и Swagger.

APItizer

Мы решили сосредоточиться только на одном сценарии — проектировании API-контрактов.

Всё остальное должно происходить автоматически.

Пользователь отвечает за:

• Проектирование контракта.

Система отвечает за:

• Генерацию документации;

• Генерацию JSON-запросов и ответов;

• Генерацию JSON Schema;

• Генерацию коллекций Postman;

• Генерацию OpenAPI-спецификаций.

Что умеет APItizer сегодня

На момент написания статьи APItizer поддерживает:

• Работу с одной коллекцией API

• Визуальное проектирование контрактов

• Импорт коллекций Postman и OpenAPI

• Экспорт в Postman и OpenAPI

• Генерацию документации

• Генерацию JSON и JSON Schema

• Настройку структуры запросов и ответов через визуальный конструктор

Коллекция объёмом более 300 контрактов обрабатывается за несколько секунд.

Подход к хранению данных

При разработке продукта мы сознательно отказались от хранения пользовательских данных на сервере.

Сейчас весь функционал доступен бесплатно.

Основные принципы продукта:

• Генерация работает на детерминированной логике (deterministic logic), без ИИ

• Данные хранятся локально, в IndexedDB

• Сервер использует временное кэширование только для ускорения генерации

Почему без ИИ?

Потому что при генерации контрактов критически важны предсказуемость, повторяемость и соответствие спецификации. Жёстко реализованная логика обеспечивает стабильный результат независимо от объёма и сложности контракта.

Что дальше

На момент публикации выпущен MVP0.

В продукте ещё есть ограничения, недостающие функции и, конечно, баги.

Сейчас для нас особенно важна обратная связь от реальных пользователей:

• Каких возможностей не хватает;

• Какие ошибки мешают работе;

• Какие сценарии использования наиболее востребованы.

Поэтому приглашаю вас попробовать APItizer и поделиться своими впечатлениями, предложениями и замечаниями.

Пример заполнения атрибутов тела запроса