tochka-developers / jsonrpc-doc
JsonRpc Doc extension for Laravel
Installs: 44
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 5
Forks: 1
Open Issues: 0
Language:CSS
Requires
- php: >=5.6.4
- illuminate/log: ~5.4
README
Описание
Генерация документации для JsonRpc-сервера на основе SMD-схемы. Адаптирован для SMD-схемы, возвращаемой оригинальным модулем Tochka-Developers/JsonRpc версии >1.1.11
Установка
Laravel
composer require tochka-developers/jsonrpc-doc
- Добавьте
Tochka\JsonRpcDoc\ServiceProvider
в список сервис-провайдеров вconfig/app.php
:
'providers' => [ //... \Tochka\JsonRpcDoc\ServiceProvider::class, ],
- Опубликуйте конфигурацию и ресурсы:
php artisan vendor:publish --tag=config
php artisan vendor:publish --tag=public
- Настройте роутинг для страниц документации (в
App\RouteServiceProvider
):
protected function mapWebRoutes() { // если хотите использовать поддомен (замените SUBDOMAIN на необходимый): // важно использовать роутинг с поддоменоном ВЫШЕ роутинга основного домена Route::group([ 'domain' => 'SUBDOMAIN.{domain}.{tld}', 'middleware' => \Tochka\JsonRpcDoc\Middleware\DomainClear::class ], function() { \Tochka\JsonRpcDoc\ServiceProvider::route(); }); // если хотите использовать префикс в пути: Route::group([ 'prefix' => 'docs' ], function() { \Tochka\JsonRpcDoc\ServiceProvider::route(); }); Route::middleware('web') ->namespace($this->namespace) ->group(base_path('routes/web.php')); }
Lumen
composer require tochka-developers/jsonrpc-doc
- Зарегистрируйте сервис-провайдер
Tochka\JsonRpcDoc\ServiceProvider
вbootstrap/app.php
:
$app->register(Tochka\JsonRpcDoc\ServiceProvider::class);
- Скопируйте конфигурацию из пакета (
vendor/tochka-developers/jsonrpc-doc/config/jsonrpcdoc.php
) в проект (config/jsonrpcdoc.php
) - Скопируйте ресурсы из пакета (
vendor/tochka-developers/jsonrpc-doc/assets/*
) в проект (public/vendor/jsonrpcdoc/*
) - Подключите конфигурацию в
bootstrap/app.php
:
$app->configure('jsonrpcdoc');
- Настройте роутинг для страниц документации в
bootstrap/app.php
:
// если хотите использовать префикс в пути: $app->group([ 'prefix' => 'docs', ], function() { \Tochka\JsonRpcDoc\ServiceProvider::route(); }); // если хотите использовать поддомен (замените SUBDOMAIN на необходимый): $app->routeMiddleware([ 'subdomain' => \Tochka\JsonRpcDoc\Middleware\SubDomain::class, ]); $app->group([ 'middleware' => 'subdomain:SUBDOMAIN', ], function() { \Tochka\JsonRpcDoc\ServiceProvider::route(); });
Настройка
Отредактируйте конфигурацию jsonrpcdoc
. Пакет позволяет выводить документацию сразу для нескольких JsonRpc-серверов.
Все используемые сервера должны быть перечислены в списке connections
конфигурации пакета.
Имя используемого по умолчанию соединения должно быть прописано в параметре default
.
Если этот параметр не указан, то в качестве соединения по умолчанию будет использовано первое соединение в списке.
Для использования нескольких документаций для каждой необходимо настроить свою точку входа.
Для этого в роутинге при вызове метода \Tochka\JsonRpcDoc\ServiceProvider::route($serviceName)
в качестве $serviceName
должно быть передано имя используемого соединения.
Если имя не передано - будет использовано соединение по умолчанию.
Если пакет tochka-developers/jsonrpc-doc
используется вместе с пакетом tochka-developers/jsonrpc
, то в качестве
url
в конфигурации можно указать значение null
. В таком случае адрес точки входа JsonRpc-сервера будет взят
из конфигурации пакета jsonrpc
. Стоит учесть, что это будет работать только в случае использования автоматического
роутинга (Ссылка на раздел документации).
Также, в случае использования нескольких точек входа - будет использована только первая в списке.
Данная возможность корректно работает только в Laravel. К сожалению, Lumen не поддерживает автоматическое получение имени текущего хоста при запуске из консоли. Вы можете самостоятельно устанавливать переменные
$_SERVER['SERVER_NAME']
и$_SERVER['SERVER_PORT']
в своем приложении при инициализации, либо прописать имя хоста в.env
:
APP_URL=http://example.org
Такое поведение обеспечивает автоматическую работу без дополнительных настроек в большинстве случаев.
Если же вы наблюдаете ошибку типа [ERROR] The host did not return the SMD-scheme. Generating a client is not possible.
,
то попробуйте прописать путь к JsonRpc-серверу в параметре url
.
После настройки соединений необходимо получить информацию о сервере (SMD-схему). Для этого выполните команду artisan:
php artisan jsonrpc:generateDocumentation
Если в результате вы увидели сообщение [OK] Saving SMD for connection "api" successfull.
, значит все прошло успешно.
Страницы документации после этого должны работать.
Модуль сохраняет схему локально и после этого использует для генерации страниц ее. Поэтому для обновления документации
необходимо снова выполнить команду jsonrpc:generateDocumentation
.