docs.vpodarok.ru — сервис документирования API

Задача

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

Решение

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

Технологии — Laravel, Alpine.js и TypeScript, MariaDB, GitLab CI. Лёгкий фронтенд без тяжёлого SPA: страницы документации быстрые и индексируются.

Результат

Одна точка правды по всем API заказчика. Новые методы описываются в интерфейсе за минуты, партнёры получают актуальную документацию и песочницу, а поддержка — меньше вопросов «как вызвать метод».