Рождение идеи.
Так получилось, что некоторые из последних проектов в нашей компании были выполнены как REST-like API на OctoberCMS + фронтенд на Nuxt.js.
Я разрабатывал первую часть и мне надо было как-то рассказывать frontend-разработчику какие роуты есть у нас в API. Для этого я поддерживал коллекцию роутов в Postman. Всё шло не плохо, пока мне, наконец, это не надоело. Тогда меня посетила мысль: "зачем мне поддерживать коллекцию в постмане, если у меня в коде уже всё есть?".
Так родилась идея создания плагина для OctoberCMS, про который я расскажу в этой статье.
Плагин GromIT.RoutesBrowser
Итак GromIT.RoutesBrowser - это плагин, который отображает в админке на отдельной странице все роуты вашего приложения (за исключением системных, и роутов темы) с документацией, собираемой из кода и докблоков с помощью Reflection API.
Самый простой способ понять, как с этим работать - это создать плагин с файлом routes.php и добавить какой-нибудь роут.
Например, что-то такое:
<?php
Route::get('/hello/{name}', [GreetController::class, 'greet']);
class GreetController extends \Illuminate\Routing\Controller
{
/**
* Returns greeting
*
* @param string $name Person name
*/
public function greet(GreetRequest $request, string $name)
{
$greeting = ($request->greeting ?: 'Hello') . ', ' . $name;
if ($request->friend) {
$greeting .= ' and ' . $request->friend;
}
return response()->json([
'greeting' => $greeting
]);
}
}
/**
* @property-read string|null $greeting Greeting. Default - "Hello"
* @property-read string|null $friend Friend name
*/
class GreetRequest extends \Illuminate\Foundation\Http\FormRequest
{
public function rules()
{
return [];
}
}
Далее, открываем страницу плагина в админке сайта и видим следующую картину:
Как видно из скриншота, информация о роуте заполнилась следующим образом:
HTTP-метод и URI роута - из самого описания роута в файле route.php
комментарий - из докблока к обработчику роута
тип и комментарий к параметру name из него же
параметры запроса с описанием типов и комментариями - из докблока к классу запроса
Также, здесь можно ввести значения параметров, добавить заголовки и выполнить тестовые запросы (пока без файлов и массивов, возможно, они будут добавлены в будущем).
Вот, собственно, и всё.
Вместо заключения
Данный плагин - не замена Postman или Swagger и он точно не предназначен для публичных API. Это скорее аналог php artisan route:list для тех, кому лень идти в терминал.
Ссылки
Оригинал статьи
Плагин на github
