Merge branch 'master' into default-url-rule

CHANGELOG.md

@@ -6,6 +6,7 @@ In order to read more about upgrading and BC breaks have a look at the [UPGRADE
 ## 3.3.0
 
 + [#503](https://github.com/luyadev/luya-module-admin/pull/503) An option to assign defined `yii\web\UrlRule` into the `luya\admin\openapi\Generator`.
++ [#501](https://github.com/luyadev/luya-module-admin/pull/501) Implement PhpDoc `@uses` for handling OpenApi request body informations when verb type is `POST`.
 + [#500](https://github.com/luyadev/luya-module-admin/pull/500) Trigger an event (eventUserAccessTokenLogin) when an access token is requesting for a login.
 + [#499](https://github.com/luyadev/luya-module-admin/pull/499) Added missing RU translations.
 + [#489](https://github.com/luyadev/luya-module-admin/issues/489) Hide default LUYA NgRest CRUD actions for OpenApi generator. Improve overall performance to generate OpenApi.

src/Module.php

@@ -272,7 +272,19 @@ final class Module extends \luya\admin\base\Module implements CoreModuleInterfac
  'api-admin-queuelogerror' => 'luya\admin\apis\QueueLogErrorController',
  'api-admin-ngrestlog' => 'luya\admin\apis\NgrestLogController',
  'api-admin-storageimage' => 'luya\admin\apis\StorageImageController',
+ ];
 
+ public $apiRules = [
+ 'api-admin-timestamp' => [
+ 'patterns' => [
+ 'POST' => 'index',
+ ]
+ ],
+ 'api-admin-user' => [
+ 'extraPatterns' => [
+ 'POST change-password' => 'change-password',
+ ]
+ ]
  ];
 
  /**

src/apis/CommonController.php

@@ -83,6 +83,7 @@ public function actionSchedulerLog($model, $pk)
  * Add a task to the scheduler.
  *
  * @return array
+ * @uses Scheduler
  * @since 2.0.0
  */
  public function actionSchedulerAdd()
@@ -159,6 +160,8 @@ public function actionTagRelationToggle($tagId, $pkId, $tableName)
  /**
  * Set the lastest ngrest filter selection in the User Settings.
  *
+ * @uses string apiEndpoint
+ * @uses string filterName
  * @return boolean
  */
  public function actionNgrestFilter()
@@ -172,6 +175,9 @@ public function actionNgrestFilter()
  /**
  * Set the lastest ngrest curd list order direction in the User Settings.
  *
+ * @uses string apiEndpoint
+ * @uses string sort
+ * @uses string field
  * @return boolean
  */
  public function actionNgrestOrder()
@@ -261,6 +267,7 @@ public function actionDataModules()
  /**
  * Save the last selected filemanager folder in the user settings.
  *
+ * @uses string folderId
  * @return boolean
  */
  public function actionSaveFilemanagerFolderState()
@@ -287,6 +294,7 @@ public function actionGetFilemanagerFolderState()
  /**
  * Store the open and closed folders from the filemanager tree in the user settings.
  *
+ * @uses array data
  * @return boolean
  */
  public function actionFilemanagerFoldertreeHistory()

src/apis/TimestampController.php

@@ -6,7 +6,6 @@
 use luya\admin\models\UserOnline;
 use luya\admin\base\RestController;
 use luya\traits\CacheableTrait;
-use luya\admin\models\Config;
 use luya\admin\models\UserAuthNotification;
 
 /**
@@ -22,6 +21,7 @@ class TimestampController extends RestController
  /**
  * The timestamp action provider informations about currenct only users and if the ui needs to be refreshed.
  *
+ * @uses integer $lastKeyStroke
  * @return array
  */
  public function actionIndex()

src/apis/UserController.php

@@ -173,6 +173,7 @@ public function actionRemoveDevice()
  * 
  * A request including body params `newpass`, `oldpass`, `newpassrepeat`.
  *
+ * @uses UserChangePassword
  * @return \luya\admin\models\UserChangePassword
  */
  public function actionChangePassword()

src/controllers/UptimeController.php

@@ -6,7 +6,7 @@
 use luya\rest\Controller;
 
 /**
- * Uptime Tests Controller.
+ * Uptime Tests
  *
  * This controler is used for uptime status robots.
  *

src/ngrest/base/Api.php

@@ -556,6 +556,7 @@ public function actionServices()
  /**
  * Toggle Notifications
  *
+ * @uses integer mute Whether should be muted or not
  * @return UserAuthNotification The user auth notification model. If model does not exists a new model will be created.
  * @since 2.0.0
  */
@@ -584,6 +585,7 @@ public function actionToggleNotification()
  *
  * Search querys with Pagination will be handled by this action.
  *
+ * @uses string $query The search term as post request.
  * @param string $query The query to lookup the database, if query is empty a post request with `query` can be used instead.
  * @return \yii\data\ActiveDataProvider
  */
@@ -761,6 +763,9 @@ public function actionActiveWindowRender()
  /**
  * Export Data
  *
+ * @uses integer header Whether header should be exported or not
+ * @uses string type The type csv oder xlsx
+ * @uses array attributes A list of attributes to export
  * @return array An array with the key `url` which contains the download path to the file
  * @throws ErrorException
  */

src/openapi/UrlRuleRouteParser.php

@@ -9,6 +9,8 @@
 use cebe\openapi\spec\RequestBody;
 use cebe\openapi\spec\Responses;
 use cebe\openapi\spec\Schema;
+use luya\admin\openapi\phpdoc\PhpDocUses;
+use luya\admin\openapi\specs\ActiveRecordToSchema;
 use luya\admin\openapi\specs\ControllerActionSpecs;
 use luya\admin\openapi\specs\ControllerSpecs;
 use Yii;
@@ -175,6 +177,49 @@ protected function getOperation(UrlRule $urlRule, $verbName)
  ])
  ]
  ]);
+ } elseif (strtoupper($verbName) == 'POST') {
+
+ // if its a post request endpoint and @uses is defined use this
+ // information as request body.
+ $useProperties = [];
+
+ /** @var PhpDocUses $use */
+ foreach ($actionSpecs->getPhpDocParser()->getUses() as $use) {
+
+ if ($use->getType()->getIsClass()) {
+ $schema = $actionSpecs->createActiveRecordSchema($use->getType()->getClassName());
+ if ($schema) {
+ $requestBody = new RequestBody([
+ 'content' => [
+ 'application/json' => new MediaType([
+ 'schema' => [
+ 'type' => 'object',
+ 'properties' => $schema->getProperties()
+ ]
+ ])
+ ]
+ ]);
+ }
+ } else {
+ $useProperties[$use->getDescription()] = new Schema([
+ 'type' => $use->getType()->getNoramlizeName(),
+ 'title' => $use->getDescription(),
+ ]);
+ }
+ }
+
+ if (!empty($useProperties)) {
+ $requestBody = new RequestBody([
+ 'content' => [
+ 'application/json' => new MediaType([
+ 'schema' => [
+ 'type' => 'object',
+ 'properties' => $useProperties,
+ ]
+ ])
+ ]
+ ]);
+ }
  }
 
  return new Operation(array_filter([

src/openapi/phpdoc/PhpDocParser.php

@@ -41,7 +41,8 @@ protected function parseDocBlockToArrays(PhpDocReflection $reflection)
  'link' => [],
  'since' => [],
  'var' => [],
- 'property' => [], // @property <type> $firstname <description>
+ 'property' => [], // @property <type> $firstname <description>,
+ 'uses' => [], // @uses <type> <description>
  ];
 
  foreach (explode(PHP_EOL, $reflection->getDocComment()) as $row) {
@@ -121,6 +122,23 @@ public function getParams()
  return $params;
  }
 
+ /**
+ * Get uses
+ *
+ * @return PhpDocUses[]
+ * @since 3.3.0
+ */
+ public function getUses()
+ {
+ $uses = [];
+
+ foreach ($this->rows['uses'] as $use) {
+ $uses[] = new PhpDocUses($this, $use);
+ }
+
+ return $uses;
+ }
+
  /**
  *
  *
@@ -178,7 +196,7 @@ public function normalizeTypes($type)
  }
 
  /**
- * Undocumented function
+ * Return
  *
  * @return PhpDocReturn
  */

src/openapi/phpdoc/PhpDocType.php

@@ -98,13 +98,13 @@ public function getClassName()
  $className = str_replace("[]", '', $this->rawName);
  if (($class = $this->testValidClassName($className))) {
  $this->_className = $class;
- return $this->name;
+ return $class;
  }
  }
 
  if (($class = $this->testValidClassName($this->rawName))) {
  $this->_className = $class;
- return $this->name;
+ return $class;
  }
 
  if (($class = $this->testValidClassName($this->name))) {
@@ -128,8 +128,7 @@ protected function testValidClassName($className)
  return $absoluteClassName;
  }
 
- // get the
-
+ // Find alias defintion `XYZ as ABC`
  $ensureClassName = $this->phpDocParser->ensureClassName($className);
  if ($ensureClassName && class_exists($ensureClassName)) {
  return $ensureClassName;

src/openapi/phpdoc/PhpDocUses.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace luya\admin\openapi\phpdoc;
+
+/**
+ * Uses PhpDoc Annotation Parser
+ * 
+ * @since 3.3.0
+ * @author Basil Suter <git@nadar.io>
+ */
+class PhpDocUses
+{
+ protected $phpDocParser;
+
+ protected $definition;
+
+ public function __construct(PhpDocParser $phpDocParser, array $definition)
+ {
+ $this->phpDocParser = $phpDocParser;
+ $this->definition = $definition;
+ }
+
+ /**
+ * Description.
+ *
+ * @return string
+ */
+ public function getDescription()
+ {
+ return isset($this->definition[2]) ? ltrim($this->definition[2], '$') : '';
+ }
+
+ /**
+ * PhpDocType
+ *
+ * @return PhpDocType
+ */
+ public function getType()
+ {
+ return new PhpDocType($this->phpDocParser, isset($this->definition[1]) ? $this->definition[1] : null);
+ }
+}

src/openapi/specs/ActiveRecordToSchema.php

@@ -3,10 +3,9 @@
 namespace luya\admin\openapi\specs;
 
 use cebe\openapi\spec\Schema;
-use luya\admin\models\ApiUser;
 use luya\admin\openapi\phpdoc\PhpDocParser;
 use ReflectionClass;
-use yii\db\BaseActiveRecord;
+use yii\base\Model;
 
 /**
  * Generate Schema Specs from Active Record.
@@ -17,7 +16,7 @@
 class ActiveRecordToSchema
 {
  /**
- * @var BaseActiveRecord
+ * @var Model
  */
  protected $activeRecord;
 
@@ -36,7 +35,7 @@ class ActiveRecordToSchema
  */
  protected $senderActiveRecordClassName;
 
- public function __construct(BaseSpecs $baseSpecs, BaseActiveRecord $activeRecord, $senderActiveRecordClassName = null)
+ public function __construct(BaseSpecs $baseSpecs, Model $activeRecord, $senderActiveRecordClassName = null)
  {
  $this->activeRecord = $activeRecord;
  $this->baseSpecs = $baseSpecs;

src/openapi/specs/BaseSpecs.php

@@ -14,6 +14,7 @@
 use ReflectionMethod;
 use Yii;
 use yii\base\Action as BaseAction;
+use yii\base\Model;
 use yii\data\ActiveDataProvider;
 use yii\db\ActiveRecord;
 use yii\rest\Action;
@@ -56,10 +57,11 @@ abstract public function getActionObject();
  abstract public function getControllerObject();
 
  private $_phpDocParser;
+
  /**
  * @return PhpDocParser
  */
- protected function getPhpDocParser()
+ public function getPhpDocParser()
  {
  if ($this->_phpDocParser === null) {
  $this->_phpDocParser = new PhpDocParser($this->getReflection());
@@ -288,7 +290,7 @@ public function createActiveRecordSchema($activeRecordClassName, $senderActiveRe
  Yii::warning("Create object createActiveRecordSchema {$activeRecordClassName}", __METHOD__);
  $object = Yii::createObject($activeRecordClassName);
 
- if ($object instanceof ActiveRecord) {
+ if ($object instanceof Model) {
  return new ActiveRecordToSchema($this, $object, $senderActiveRecordClassName);
  }
  } catch(\Exception $e) {

src/resources/js/controllers.js

@@ -1175,7 +1175,7 @@
  $scope.notifications = [];
 
  (function tick(){
- $http.post('admin/api-admin-timestamp/index', {lastKeyStroke: $scope.lastKeyStroke}, {ignoreLoadingBar: true}).then(function(response) {
+ $http.post('admin/api-admin-timestamp', {lastKeyStroke: $scope.lastKeyStroke}, {ignoreLoadingBar: true}).then(function(response) {
  $scope.forceReload = response.data.forceReload;
  $scope.notifications = response.data.notifications;
  if ($scope.forceReload && !$scope.visibleAdminReloadDialog) {