diff --git a/README.md b/README.md index 8d4dfb7..d3781b3 100644 --- a/README.md +++ b/README.md @@ -11,15 +11,14 @@ | NO | auth | 鉴权状态
`NO`: 关闭
`YES`: 开启, 通过SDK访问时需要鉴权 | | -- | name | 项目名称
导出文档在`POSTMAN`工具中显示的项目名称
注: 若不指定则使用应用配置项`app.appName`的值 | | -- | description | 项目描述
导出文档在`POSTMAN`工具中显示的一段项目描述信息 | -| -- | host | 域名前缀
固定前缀后, 适配在`POSTMAN`工具中, 按环境选择切换域名后缀, 实现一份文档多环境共用 | -| -- | sdk | SDK类名
导出文档时, 同步导出`PHP`版本的Class/类, 实际应用时, 将导出的文件复制到[SDK](https://github.com/uniondrug/service-sdk)项目即可 | -| -- | sdkService | SDK服务名
在Consul数据中心注册的服务名称, 非特殊情况一律使用域名前缀 | | -- | sdkLink | 出入参文档连接
在导出的SDK类中, 每个方法的PHPDOC片段中, 加入原始项目的连接地址前缀 | + ```json { - "name" : "", - "description" : "" + "name" : "异步消息双向转发", + "description" : "基于阿里云MNS的异消息双向转发, 应用端调用", + "sdkLink" : "https://uniondrug.coding.net/p/module.mbs2/git/tree/development" } ``` diff --git a/src/Parsers/Collection.php b/src/Parsers/Collection.php index 45a951a..12d709e 100644 --- a/src/Parsers/Collection.php +++ b/src/Parsers/Collection.php @@ -7,6 +7,7 @@ use App\Errors\Code; use Phalcon\Di; +use Uniondrug\Framework\Container; use Uniondrug\Postman\Parsers\Abstracts\Base; /** @@ -26,8 +27,28 @@ class Collection extends Base * @var string */ public $name = ''; + /** + * SDK类名 + * 如: mbs2 + * @var string + */ public $sdk = ''; + /** + * SDK路径 + * 如: module + * @var string + */ + public $sdkPath = ''; + /** + * SDK服务名 + * 如: mbs2.module + * @var string + */ public $sdkService = ''; + /** + * 目标应用文档连接前缀 + * @var string + */ public $sdkLink = ''; public $prefix = ''; /** @@ -67,21 +88,15 @@ public function __construct(string $path) parent::__construct(); $this->basePath = $path; // 1. load config - $file = $path.'/postman.json'; - if (file_exists($file)) { - $text = file_get_contents($file); - $json = json_decode($text); - if ($json instanceof \stdClass) { - isset($json->name) && $this->name = $json->name; - isset($json->description) && $this->description = $json->description; - isset($json->host) && $this->host = $json->host; - isset($json->auth) && $this->auth = strtoupper($json->auth) === 'YES'; - isset($json->sdk) && $this->sdk = $json->sdk; - isset($json->sdkService) && $this->sdkService = $json->sdkService; - isset($json->sdkLink) && $this->sdkLink = $json->sdkLink; - $this->sdkService === '' && $this->sdkService = $this->sdk; - } - } + $json = $this->initPostmanJson(); + $this->name = $json->name; + $this->description = $json->description; + $this->host = $json->host; + $this->auth = strtoupper($json->auth) === 'YES'; + $this->sdk = $json->sdk; + $this->sdkPath = $json->sdkPath; + $this->sdkService = $json->sdkService; + $this->sdkLink = $json->sdkLink; $this->sdkx = new Sdkx($this); // 2. console $this->console->info("{$json->name}, {$json->description}"); @@ -194,6 +209,64 @@ public function toPostman() return json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE); } + /** + * JSON配置文件 + * @return \stdClass + */ + private function initPostmanJson() + { + /** + * 1. 初始化POSTMAN配置 + * @var Container $di + */ + $di = Di::getDefault(); + $data = new \stdClass(); + // 1.1 通过appName计算 + // sdk + // sdkPath + $appName = $di->getConfig()->path('app.appName'); + $appName = preg_replace("/\-/", '.', $appName); + $appNameArr = explode('.', $appName); + $appNameDesc = []; + for ($i = count($appNameArr) - 1; $i >= 0; $i--) { + $appNameDesc[] = $appNameArr[$i]; + } + $sdkPath = array_pop($appNameArr); + if (!in_array($sdkPath, [ + 'backend', + 'module', + 'union' + ]) + ) { + $this->console->warning("应用名称在配置文件[config/app.php]中的[appName]字段值不合法, 必须以module、union、backend结尾"); + } + $sdkClass = preg_replace_callback("/[\.|\-](\w)/", function($a){ + return strtoupper($a[1]); + }, implode('.', $appNameArr)); + // 1.2 赋初始值 + $data->auth = "NO"; + $data->name = $appName; + $data->description = $appName; + $data->host = $appName; + $data->sdk = $sdkClass; + $data->sdkPath = $sdkPath; + $data->sdkService = $appName; + $data->sdkLink = "https://uniondrug.coding.net/p/".implode(".", $appNameDesc)."/git/blob/development";; + // 2. 配置文件优选级 + $path = "{$this->basePath}/postman.json"; + if (file_exists($path)) { + $json = file_get_contents($path); + $conf = json_decode($json); + if (is_object($conf)) { + isset($conf->auth) && $conf->auth !== "" && $data->auth = $conf->auth; + isset($conf->name) && $conf->name !== "" && $data->name = $conf->name; + isset($conf->description) && $conf->description !== "" && $data->description = $conf->description; + isset($conf->sdkLink) && $conf->sdkLink !== "" && $data->sdkLink = $conf->sdkLink; + } + } + return $data; + } + /** * 扫描Controller目录 * @param string $path diff --git a/src/Parsers/Method.php b/src/Parsers/Method.php index 5a4934a..e86d2c2 100644 --- a/src/Parsers/Method.php +++ b/src/Parsers/Method.php @@ -240,20 +240,25 @@ private function sdkText() $text = '### SDK'.$this->eol; // 2.1 if ($this->collection->sdk !== '') { - $text .= '*用法(1)*'.$this->eol; + $text .= '**`一类用法`**'.$this->eol; $text .= '```'.$this->crlf; - $text .= '// 参数设置见入参段落'.$this->crlf; - $text .= '$body = []; // 入参'.$this->crlf; - $text .= '$response = $this->serviceSdk->'.$this->collection->sdk.'->'.$this->annotation->sdkName.'($body);'.$this->crlf; + $text .= '// [推荐]推荐使用本用法'.$this->crlf; + $text .= '// 不足之处, 需发布导出的['.ucfirst($this->collection->sdk).'Sdk.php]文件到SDK项目下'.$this->crlf; + $text .= '// 并创建release版本, 调用方执行composer update完成更新'.$this->crlf; + $text .= '// SDK项目地址 https://github.com/uniondrug/service-sdk'.$this->crlf; + $text .= '$body = [];'.$this->crlf; + $text .= '$response = $this->serviceSdk->'.lcfirst($this->collection->sdkPath).'->'.$this->collection->sdk.'->'.lcfirst($this->annotation->sdkName).'($body);'.$this->crlf; $text .= '```'; $text .= $this->eol; } // 2.2 $host = "{$this->controller->collection->host}://".preg_replace("/^\/+/", '', $this->controller->annotation->prefix.$this->annotation->path); - $text .= '*用法(2)*'.$this->eol; + $text .= '_`二类用法`_'.$this->eol; $text .= '```'.$this->crlf; - $text .= '// 参数设置见入参段落'.$this->crlf; - $text .= '$body = []; // 入参'.$this->crlf; + $text .= '// [慎用]不推荐'.$this->crlf; + $text .= '// 该用法需要你知道域名前缀及路径路径, 同时不便于后期维护'.$this->crlf; + $text .= '// 一经修改将有大量项目及文件(调用方)同步修改'.$this->crlf; + $text .= '$body = [];'.$this->crlf; $text .= '$response = $this->serviceSdk->'.strtolower($this->annotation->method); $text .= '("'.$host.'", $body);'.$this->crlf; $text .= '```'.$this->eol; diff --git a/src/Parsers/Sdkx.php b/src/Parsers/Sdkx.php index 57368bc..bbbdf86 100644 --- a/src/Parsers/Sdkx.php +++ b/src/Parsers/Sdkx.php @@ -77,20 +77,21 @@ private function renderClass(string $class) * 2. 本脚本在生成时, 依赖所在项目的Controller有 `@Sdk method`定义, * 同时, 项目根目录下的`postman.json`需有`sdk`、`sdkLink`定义 * 3. 发布SDK，请将本文件放到`uniondrug/service-sdk`项目 - * 的`src/Modules`目录下，并发重新发布release版本. + * 的`src/Exports/{{NAMESPACE}}`目录下，并发重新发布release版本. * @author {{AUTHOR}} * @date {{DATE}} * @time {{TIME}} */ -namespace Uniondrug\ServiceSdk\Modules; +namespace Uniondrug\ServiceSdk\Exports\{{NAMESPACE}}; +use Uniondrug\ServiceSdk\Exports\Abstracts\SdkBase; use Uniondrug\ServiceSdk\Responses\ResponseInterface; /** * {{CLASS}} * @package Uniondrug\ServiceSdk\Modules */ -class {{CLASS}} extends Abstracts\SdkBase +class {{CLASS}} extends SdkBase { /** * 服务名称 @@ -107,6 +108,7 @@ class {{CLASS}} extends Abstracts\SdkBase 'AUTHOR' => 'PostmanCommand', 'DATE' => date('Y-m-d'), 'TIME' => date('r'), + 'NAMESPACE' => ucfirst($this->collection->sdkPath)."s", 'CLASS' => $class, 'SERVICE' => $this->collection->sdkService, 'METHODS' => $this->renderMethods()