Поддержка внутренней документации к REST API в OctoberCMS

Рождение идеи.

Так получилось, что некоторые из последних проектов в нашей компании были выполнены как REST-like API на OctoberCMS + фронтенд на Nuxt.js.

Я разрабатывал первую часть и мне надо было как-то рассказывать frontend-разработчику какие роуты есть у нас в API. Для этого я поддерживал коллекцию роутов в Postman. Всё шло не плохо, пока мне, наконец, это не надоело. Тогда меня посетила мысль: "зачем мне поддерживать коллекцию в постмане, если у меня в коде уже всё есть?".

Так родилась идея создания плагина для OctoberCMS, про который я расскажу в этой статье.

Плагин GromIT.RoutesBrowser

Итак GromIT.RoutesBrowser - это плагин, который отображает в админке на отдельной странице все роуты вашего приложения (за исключением системных, и роутов темы) с документацией, собираемой из кода и докблоков с помощью Reflection API.

Самый простой способ понять, как с этим работать - это создать плагин с файлом routes.php и добавить какой-нибудь роут.

Например, что-то такое:

Далее, открываем страницу плагина в админке сайта и видим следующую картину:

Как видно из скриншота, информация о роуте заполнилась следующим образом:

HTTP-метод и URI роута - из самого описания роута в файле route.php
комментарий - из докблока к обработчику роута
тип и комментарий к параметру name из него же
параметры запроса с описанием типов и комментариями - из докблока к классу запроса

Также, здесь можно ввести значения параметров, добавить заголовки и выполнить тестовые запросы (пока без файлов и массивов, возможно, они будут добавлены в будущем).

Вот, собственно, и всё.

Вместо заключения

Данный плагин - не замена Postman или Swagger и он точно не предназначен для публичных API. Это скорее аналог php artisan route:list для тех, кому лень идти в терминал.

Скачать плагин: