README

描述

基于 SMD 方案的 JsonRpc 服务器文档生成器。已适配 Tochka-Developers/JsonRpc 版本 >1.1.11 返回的 SMD 方案。

安装

Laravel

1. composer require tochka-developers/jsonrpc-doc
2. 将 Tochka\JsonRpcDoc\ServiceProvider 添加到 config/app.php 中的服务提供商列表

'providers' => [
    //...
    \Tochka\JsonRpcDoc\ServiceProvider::class,
],

1. 发布配置和资源

php artisan vendor:publish --tag=config
php artisan vendor:publish --tag=public

1. 在 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

1. composer require tochka-developers/jsonrpc-doc
2. 在 bootstrap/app.php 中注册服务提供商 Tochka\JsonRpcDoc\ServiceProvider

$app->register(Tochka\JsonRpcDoc\ServiceProvider::class);

1. 将配置从包中（vendor/tochka-developers/jsonrpc-doc/config/jsonrpcdoc.php）复制到项目中（config/jsonrpcdoc.php）
2. 将资源从包中（vendor/tochka-developers/jsonrpc-doc/assets/*）复制到项目中（public/vendor/jsonrpcdoc/*）
3. 在 bootstrap/app.php 中连接配置

$app->configure('jsonrpcdoc');

1. 在 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 包一起使用，则可以将配置中的 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. 的错误，请尝试在 url 参数中指定 JsonRpc 服务器的路径。

设置连接后，需要获取服务器信息（SMD 方案）。为此，请执行 artisan 命令

php artisan jsonrpc:generateDocumentation

如果您看到消息 [OK] Saving SMD for connection "api" successfull.，则表示一切顺利。设置之后，文档页面应该可以工作。模块将本地保存方案并随后用于生成页面。因此，要更新文档，需要再次执行 jsonrpc:generateDocumentation 命令。