API Сервисы: документация и тестирование эндпоинтов прямо в админ-панели
До этого, чтобы проверить как отрабатывает конкретный метод API, нужно было открывать Postman, искать нужную коллекцию, вспоминать какой токен и в каком заголовке нужен именно для этого сервиса, копировать актуальный URL из кода — и только потом смотреть на ответ. Если метод принимал параметры, приходилось лезть в исходники или в собственную память, чтобы вспомнить их названия, типы и что из них обязательно. Документация по эндпоинтам жила в голове, в разрозненных файлах и устаревших Postman-коллекциях, а не в одном месте, актуальном для всех сервисов сразу. Я сделал модуль «API Сервисы» в admin-панели — живой каталог всех эндпоинтов проекта с документацией и возможностью выполнить запрос одним кликом.
Модуль решает сразу несколько задач. Документация: для каждого сервиса — Vuecraft, Airlines, Expost, блог, портфолио, локали и другие — виден полный список методов с человекочитаемым описанием, query/path/body параметрами, их типами, значениями по умолчанию и тем, обязательны они или нет. Тестирование: рядом с описанием метода есть строка с URL и кнопка «Execute», которая отправляет запрос и тут же показывает ответ — код статуса, время выполнения, размер и сам JSON с подсветкой синтаксиса. Управление каталогом: список сервисов и их методов больше не статический файл в коде, а данные в базе, которые редактируются через отдельную форму — добавить новый эндпоинт или поправить описание параметра можно прямо из браузера, без пересборки панели.
Список сервисов
Модуль открывается таблицей всех зарегистрированных сервисов. У каждой строки — небольшая круглая иконка слева (загруженная картинка или первая буква названия на цветном фоне, если иконку не загружали), ID сервиса — тот самый slug, который используется в URL страницы тестирования, название, описание и количество маршрутов.
Строка целиком кликабельна и ведёт на форму редактирования — не нужно искать отдельную кнопку «Открыть». В правом краю строки — четыре управляющих элемента: две стрелки для перемещения сервиса вверх или вниз в списке и стандартные кнопки редактирования и удаления.
Перемещение стрелками работает мгновенно: клик меняет порядок сразу, без отдельного сохранения или перезагрузки страницы — список просто перерисовывается в новом порядке. Именно этот порядок и используется в боковом меню панели, где сервисы перечислены в разделе «API Сервисы».
Кнопка «+ Добавить сервис» в шапке блока ведёт на пустую форму создания.
Интерактивный обзор API
Клик по сервису в боковом меню открывает страницу тестирования — центральный экран модуля. Сверху — заголовок и описание сервиса, и справа кнопка-ссылка «Swagger ↗», которая в новой вкладке открывает полную техническую документацию для тех, кому нужны мелкие детали схемы.
Дальше — список методов сервиса, каждый в отдельной карточке. В шапке карточки — цветной бейдж с HTTP-методом (GET зелёный, POST фиолетовый, PUT и PATCH жёлтые, DELETE красный), сам путь запроса моноширинным шрифтом и короткое название метода, чтобы не угадывать назначение по одному URL.
Документация параметров
Под заголовком карточки — развёрнутое описание метода и, если параметры заданы, до трёх отдельных таблиц: Query, Path и Body. В каждой строке таблицы — имя параметра моноширинным шрифтом, тип (string, int, boolean, object), бейдж обязательности («required» красным или «optional» серым), значение по умолчанию и текстовое описание. Если у метода вообще нет параметров, вместо пустых таблиц показывается курсивная подсказка «Параметры не требуются» — так сразу понятно, что это не баг и не недогруженные данные.
У query-параметров есть пятая колонка — поле ввода значения прямо в таблице документации. Вписал туда что-то — значение тут же подставляется в строку запроса ниже, без необходимости вручную редактировать URL. Когда поле заполнено, рядом появляется маленький крестик: убирает параметр и из таблицы, и из URL одним кликом. Path-параметры показываются с двоеточием перед именем (:id) — так же, как они выглядят в реальном маршруте Express — а body-параметры описывают поля JSON, которое нужно отправить в теле запроса.
Выполнение запроса
Ниже таблиц — строка запроса: редактируемое поле с полным URL и кнопка «Execute». URL можно поправить руками — например, дописать параметр, которого нет в документации, или изменить значение прямо в строке. Если получившийся URL отличается от исходного значения метода, слева от кнопки выполнения появляется кнопка сброса со стрелкой — наведение на неё показывает подсказку с тем, к какому URL вернётся поле. Для методов, принимающих тело запроса (POST, PUT, PATCH), под строкой URL появляется текстовая область для JSON — с моноширинным шрифтом и плейсхолдером {"key": "value"}, чтобы было видно ожидаемый формат.
Кнопка «Execute» во время выполнения запроса меняет подпись на анимированные точки и блокируется — повторное нажатие не уйдёт вторым запросом, пока первый не завершился. Запрос можно отправить и не трогая мышь — клавиша Enter в строке URL делает то же самое.
Ответ
После выполнения запроса под карточкой раскрывается блок ответа. В его шапке — сразу несколько метрик: цветной бейдж кода статуса (зелёный для 2xx, синий для 3xx, оранжевый для 4xx, красный для 5xx), время выполнения в миллисекундах, размер ответа в человекочитаемом виде (байты, КБ или МБ — в зависимости от объёма) и, если в ответе есть массив или поле вроде total, акцентный бейдж с количеством элементов — не нужно считать строки вручную, чтобы понять сколько записей вернулось. Рядом — время последнего выполнения запроса в формате часы:минуты:секунды, чтобы при возврате к экрану было видно, не устарел ли показанный ответ.
Кнопка «Копировать» в этой же строке забирает весь JSON ответа в буфер обмена и на полторы секунды меняет подпись на «✓ Скопировано» — без отдельного всплывающего уведомления, прямо на самой кнопке. Если запрос завершился с ошибкой сети — вместо JSON показывается короткое текстовое сообщение об ошибке красным цветом, без бейджа статуса.
Сам ответ выводится не голым текстом, а с подсветкой синтаксиса — тот же редактор кода, что уже используется в модуле «Файлы» для просмотра содержимого файлов, только в режиме «только для чтения» и с языком, зафиксированным как JSON. Ключи объекта подсвечены одним цветом, строковые значения другим, числа, булевы значения и null — третьим, четвёртым и пятым: глазами сразу видно структуру ответа, а не серую стену текста. Если ответ большой, область с JSON ограничена по высоте и скроллится отдельно от страницы, длинные строки переносятся, а не вылезают за край экрана. Пока новый запрос выполняется повторно — старый ответ остаётся видимым, но притухает, явно показывая, что данные сейчас обновляются.
Редактор сервиса
Управление самим каталогом — отдельная форма, до которой можно добраться кнопками «+ Добавить сервис» из списка или «Редактировать» у конкретной строки.
Основные поля и иконка
Сверху формы — блок иконки: квадратное превью 64×64 слева, кнопки «Загрузить» и «Убрать» справа. Принимаются PNG, JPG, WebP и SVG до 2 МБ. При создании нового сервиса файл иконки сначала просто показывается локальным превью — реальная загрузка на сервер происходит уже после того, как сервис создан и получил свой ID; при редактировании существующего сервиса загрузка происходит сразу.
Дальше — обязательные текстовые поля: ID (slug сервиса — только латинские буквы в нижнем регистре, цифры и дефис; это значение становится частью URL страницы тестирования, поэтому после создания сервиса оно становится нереактивным и не редактируется), название, краткое описание и ссылка на Swagger-документацию — поле показывает только редактируемый «хвост» пути, неизменяемый префикс /api/ выводится перед полем и в само значение не попадает.
При создании нового сервиса, если в каталоге уже есть другие сервисы, появляется ещё одно поле — после какого из существующих сервисов разместить новый в списке и в боковом меню. По умолчанию выбран последний сервис в текущем порядке, то есть новый сервис попадёт в конец списка, если не указать иное.
Маршруты
Ниже — блок «Маршруты» с кнопкой «+ Добавить маршрут» в шапке. Если маршрутов ещё нет, вместо пустого блока — подсказка нажать эту кнопку. Каждый маршрут — отдельная карточка с собственной рамкой, чтобы границы между методами были видны сразу, без необходимости считать отступы.
В шапке карточки — выпадающий список HTTP-метода (GET, POST, PUT, DELETE, PATCH), поле для окончания URL с автоматически подставленным неизменяемым префиксом (тот самый href сервиса, выбранный чуть выше в форме) и кнопка удаления карточки — компактная, с тем же оформлением, что и везде в панели, и красной подсветкой при наведении, чтобы destructive-действие визуально выделялось.
Дальше — короткое название метода (то, что видно рядом с путём на странице тестирования) и подробное описание — многострочное поле для полноценного объяснения, что метод делает. Если выбранный HTTP-метод поддерживает тело запроса, появляется ещё одно поле — пример тела в формате JSON, который будет предзаполнен на странице тестирования.
Параметры маршрута
В нижней части каждой карточки маршрута — три вкладки: Query, Path и Body. Переключение между ними не теряет введённые данные — на каждой вкладке свой независимый список параметров. Кнопка «+ Параметр» добавляет пустую строку в таблицу активной вкладки.
Таблица параметров — поле имени (моноширинным шрифтом), выпадающий список типа (string, int, boolean, object), переключатель обязательности и поле значения по умолчанию, которое меняет вид в зависимости от выбранного типа: для boolean — выпадающий список «true/false», для object — текстовая область для JSON, для остальных типов — обычное текстовое поле. Последняя колонка — описание параметра, то самое, что попадёт в документацию на странице тестирования. Удаление параметра — крестик в конце строки.
Сохранение формы происходит в два шага: сначала уходят на сервер поля самого сервиса (название, описание, ссылка, иконка), затем весь список маршрутов синхронизируется одним запросом целиком — удалённые в форме карточки пропадают из базы, изменённые обновляются, новые создаются с собственным ID. Сразу после сохранения форма возвращает на список сервисов, а изменения уже доступны и в боковом меню, и на странице тестирования — без перезагрузки панели и без выкладки нового релиза.
Технически
Раньше список сервисов и их методов был статическим TypeScript-файлом, подключённым прямо в код панели — добавить новый эндпоинт или поправить описание параметра означало менять файл и пересобирать фронтенд. Сейчас это две таблицы в PostgreSQL: сервисы и их маршруты, связанные внешним ключом с каскадным удалением — удалили сервис, его маршруты удалились автоматически, без отдельного запроса на очистку. Боковое меню, страница тестирования и редактор работают с одной и той же REST-обвязкой над этими таблицами, поэтому изменения в одном месте сразу видны во всех остальных.
Порядок отображения сервисов в списке и в меню — обычное целочисленное поле sortOrder. Стрелки вверх/вниз на странице списка не пересчитывают порядок у всех строк, а просто меняют значение sortOrder местами у двух соседних сервисов — минимум изменений в базе на каждый клик и понятная, предсказуемая сортировка.
Документация параметров метода (query, path, body) хранится в одном JSON-поле на маршрут, а не в отдельных таблицах с фиксированной схемой — это позволяет произвольно добавлять и убирать параметры без изменения структуры базы при каждом новом случае. Форма редактора превращает содержимое этого поля в три отдельные таблицы с типизированными значениями по умолчанию, а страница тестирования — обратно в реальные query-параметры строки запроса и тело запроса.
Подсветка синтаксиса в блоке ответа — переиспользование того же компонента редактора кода, что уже стоит в файловом менеджере для просмотра содержимого файлов, просто переключённого в режим «только для чтения» с языком, принудительно зафиксированным как JSON. Не пришлось подключать в проект ещё одну библиотеку подсветки синтаксиса — один и тот же компонент одинаково хорошо показывает и содержимое файла на диске, и произвольный ответ API.