Merge pull request #2110 from dasgarner/docs/missing_module_api

Modules/Widgets: add further swagger documentation.

README.md

@@ -71,11 +71,9 @@ git clone [email protected]:<your_id>/xibo-cms.git xibo-cms
 
 We maintain the following branches. To contribute to Xibo please also use the `develop` branch as your base.
 
-- develop: Work in progress toward 4.0
-- master: Currently 3.3
-- release32: Bug fixes for 3.2
-- release31: Bug fixes for 3.1
-- release30: Bug fixes 3.0
+- develop: Work in progress toward 4.0.x
+- master: Currently 4.0
+- release33: Bug fixes for 3.3
 - release23: Bug fixes for 2.3
 - release18: Archive of 1.8
 - release17: Archive of 1.7

lib/Controller/Module.php

@@ -21,12 +21,14 @@
  */
 namespace Xibo\Controller;
 
+use Psr\Http\Message\ResponseInterface;
 use Slim\Http\Response as Response;
 use Slim\Http\ServerRequest as Request;
 use Xibo\Factory\ModuleFactory;
 use Xibo\Factory\ModuleTemplateFactory;
 use Xibo\Storage\StorageServiceInterface;
 use Xibo\Support\Exception\AccessDeniedException;
+use Xibo\Support\Exception\ControllerNotImplemented;
 use Xibo\Support\Exception\GeneralException;
 use Xibo\Support\Exception\InvalidArgumentException;
 use Xibo\Support\Exception\NotFoundException;
@@ -72,7 +74,18 @@ public function displayPage(Request $request, Response $response)
     }
 
     /**
-     * A grid of modules
+     * @SWG\Get(
+     *  path="/module",
+     *  operationId="moduleSearch",
+     *  tags={"module"},
+     *  summary="Module Search",
+     *  description="Get a list of all modules available to this CMS",
+     *  @SWG\Response(
+     *      response=200,
+     *      description="successful operation",
+     *      @SWG\Schema(ref="#/definitions/Module")
+     *  )
+     * )
      * @param Request $request
      * @param Response $response
      * @return \Psr\Http\Message\ResponseInterface|Response
@@ -152,8 +165,9 @@ public function grid(Request $request, Response $response)
      *  @SWG\Response(
      *      response=200,
      *      description="successful operation",
-     *      @SWG\Schema(ref="#/definitions/Module")
+     *      @SWG\Schema(ref="#/definitions/Property")
      *  )
+     * )
      * @param Request $request
      * @param Response $response
      * @param $id
@@ -304,7 +318,25 @@ public function clearCache(Request $request, Response $response, $id)
     }
 
     /**
-     * Get a list of templates available for a particular data type
+     * @SWG\Get(
+     *  path="/module/templates/{dataType}",
+     *  operationId="moduleTemplateSearch",
+     *  tags={"module"},
+     *  summary="Module Template Search",
+     *  description="Get a list of templates available for a particular data type",
+     *  @SWG\Parameter(
+     *      name="dataType",
+     *      in="path",
+     *      description="DataType to return templates for",
+     *      type="string",
+     *      required=true
+     *   ),
+     *  @SWG\Response(
+     *      response=200,
+     *      description="An array of module templates for the provided datatype",
+     *      @SWG\Schema(ref="#/definitions/ModuleTemplate")
+     *  )
+     * )
      * @param \Slim\Http\ServerRequest $request
      * @param \Slim\Http\Response $response
      * @param string $dataType
@@ -353,14 +385,15 @@ public function templateGrid(Request $request, Response $response, string $dataT
      *          additionalProperties={"id":"string", "type":"string", "title":"string", "helpText":"string", "options":"array"}
      *      )
      *  )
+     * )
      * @param Request $request
      * @param Response $response
-     * @param $id
-     * @return \Psr\Http\Message\ResponseInterface|Response
-     * @throws AccessDeniedException
+     * @param string $dataType
+     * @param string $id
+     * @return ResponseInterface|Response
      * @throws GeneralException
      * @throws NotFoundException
-     * @throws \Xibo\Support\Exception\ControllerNotImplemented
+     * @throws ControllerNotImplemented
      */
     // phpcs:enable
     public function getTemplateProperties(Request $request, Response $response, string $dataType, string $id)

lib/Entity/Module.php

@@ -176,7 +176,10 @@ class Module implements \JsonSerializable
     /** @var \Xibo\Widget\Definition\Stencil|null Stencil for this modules HTML cache */
     public $stencil;
 
-    /** @var \Xibo\Widget\Definition\Property[]|null */
+    /**
+     * @SWG\Property(description="Properties to display in the property panel and supply to stencils")
+     * @var \Xibo\Widget\Definition\Property[]|null
+     */
     public $properties;
 
     /** @var \Xibo\Widget\Definition\Asset[]|null */
@@ -247,21 +250,13 @@ class Module implements \JsonSerializable
     public $defaultDuration;
 
     /**
-     * @SWG\Property(
-     *     description="An array of additional module specific settings",
-     *     type="array",
-     *     @SWG\Items(type="string")
-     * )
+     * @SWG\Property(description="An array of additional module specific settings")
      * @var \Xibo\Widget\Definition\Property[]
      */
     public $settings = [];
 
     /**
-     * @SWG\Property(
-     *     description="An array of additional module specific group properties",
-     *     type="array",
-     *     @SWG\Items(type="string")
-     * )
+     * @SWG\Property(description="An array of additional module specific group properties")
      * @var \Xibo\Widget\Definition\PropertyGroup[]
      */
     public $propertyGroups = [];
@@ -276,13 +271,22 @@ class Module implements \JsonSerializable
      */
     public $requiredElements = [];
 
-    /** @var bool $isInstalled Is this module installed? */
+    /**
+     * @SWG\Property()
+     * @var bool $isInstalled Is this module installed?
+     */
     public $isInstalled;
 
-    /** @var bool $isError Does this module have any errors? */
+    /**
+     * @SWG\Property()
+     * @var bool $isError Does this module have any errors?
+     */
     public $isError;
 
-    /** @var string[] $errors An array of errors this module has. */
+    /**
+     * @SWG\Property()
+     * @var string[] $errors An array of errors this module has.
+     */
     public $errors;
 
     // </editor-fold>

lib/Entity/ModuleTemplate.php

@@ -26,6 +26,7 @@
 use Xibo\Factory\ModuleTemplateFactory;
 use Xibo\Service\LogServiceInterface;
 use Xibo\Storage\StorageServiceInterface;
+use Xibo\Widget\Definition\Asset;
 
 /**
  * Represents a module template
@@ -36,28 +37,44 @@ class ModuleTemplate implements \JsonSerializable
     use EntityTrait;
     use ModulePropertyTrait;
 
-    /** @var string The templateId */
+    /**
+     * @SWG\Property()
+     * @var string The templateId
+     */
     public $templateId;
 
-    /** @var string Type of template (static|element|stencil) */
+    /**
+     * @SWG\Property()
+     * @var string Type of template (static|element|stencil)
+     */
     public $type;
 
-    /** @var \Xibo\Widget\Definition\Extend|null If this template extends another */
+    /**
+     * @SWG\Property()
+     * @var \Xibo\Widget\Definition\Extend|null If this template extends another
+     */
     public $extends;
 
-    /** @var string The datatype of this template */
+    /**
+     * @SWG\Property()
+     * @var string The datatype of this template
+     */
     public $dataType;
 
-    /** @var string The title */
+    /**
+     * @SWG\Property()
+     * @var string The title
+     */
     public $title;
 
     /**
-     * Icon
-     * @var string
+     * @SWG\Property()
+     * @var string Icon
      */
     public $icon;
 
     /**
+     * @SWG\Property()
      * Thumbnail
      * this is the location to a module template's thumbnail, which should be added to the installation
      * relative to the module class file.
@@ -83,26 +100,34 @@ class ModuleTemplate implements \JsonSerializable
      */
     public $showIn = 'both';
 
-    /** @var \Xibo\Widget\Definition\Property[]|null */
+    /**
+     * @SWG\Property()
+     * @var \Xibo\Widget\Definition\Property[]|null Properties
+     */
     public $properties;
 
-    /** @var bool Is Visible? */
+    /**
+     * @SWG\Property()
+     * @var bool Is Visible?
+     */
     public $isVisible = true;
 
     /**
-     * @SWG\Property(
-     *     description="An array of additional module specific group properties",
-     *     type="array",
-     *     @SWG\Items(type="string")
-     * )
+     * @SWG\Property(description="An array of additional module specific group properties")
      * @var \Xibo\Widget\Definition\PropertyGroup[]
      */
     public $propertyGroups = [];
 
-    /** @var \Xibo\Widget\Definition\Stencil|null */
+    /**
+     * @SWG\Property()
+     * @var \Xibo\Widget\Definition\Stencil|null A stencil, if needed
+     */
     public $stencil;
 
-    /** @var  */
+    /**
+     * @SWG\Property()
+     * @var Asset[]
+     */
     public $assets;
 
     /** @var string A Renderer to run if custom rendering is required. */

lib/Widget/Definition/Element.php

@@ -23,6 +23,7 @@
 namespace Xibo\Widget\Definition;
 
 /**
+ * @SWG\Definition()
  * A class representing an instance of an element template
  */
 class Element implements \JsonSerializable

lib/Widget/Definition/Extend.php

@@ -23,6 +23,7 @@
 namespace Xibo\Widget\Definition;
 
 /**
+ * @SWG\Definition()
  * A class representing one template extending another
  */
 class Extend implements \JsonSerializable

lib/Widget/Definition/LegacyType.php

@@ -24,6 +24,7 @@
 
 /**
  * A Legacy Type
+ * @SWG\Definition()
  */
 class LegacyType implements \JsonSerializable
 {

lib/Widget/Definition/Option.php

@@ -23,14 +23,33 @@
 namespace Xibo\Widget\Definition;
 
 /**
- * Option
- * typically used when paired with a dropdown
+ * Option: typically used when paired with a dropdown
+ * @SWG\Definition()
  */
 class Option implements \JsonSerializable
 {
+    /**
+     * @SWG\Property(description="Name")
+     * @var string
+     */
     public $name;
+
+    /**
+     * @SWG\Property(description="Image: optional image asset")
+     * @var string
+     */
     public $image;
+
+    /**
+     * @SWG\Property(description="Set")
+     * @var string[]
+     */
     public $set = [];
+
+    /**
+     * * @SWG\Property(description="Title: shown in the dropdown/select")
+     * @var string
+     */
     public $title;
 
     /**

lib/Widget/Definition/Property.php

@@ -32,17 +32,41 @@
 
 /**
  * A Property
+ * @SWG\Definition()
  */
 class Property implements \JsonSerializable
 {
+    /**
+     * @SWG\Property(description="ID, saved as a widget option")
+     * @var string
+     */
     public $id;
+
+    /**
+     * @SWG\Property(description="Type, determines the field type")
+     * @var string
+     */
     public $type;
+
+    /**
+     * @SWG\Property(description="Title: shown in the property panel")
+     * @var string
+     */
     public $title;
+
+    /**
+     * @SWG\Property(description="Help Text: shown in the property panel")
+     * @var string
+     */
     public $helpText;
 
     /** @var \Xibo\Widget\Definition\Rule  */
     public $validation;
 
+    /**
+     * @SWG\Property()
+     * @var string An optional default value
+     */
     public $default;
 
     /** @var \Xibo\Widget\Definition\Option[] */

lib/Widget/Definition/PropertyGroup.php

@@ -24,6 +24,7 @@
 
 /**
  * A class representing an instance of a group property to put a property in assigned Tab
+ * @SWG\Definition()
  */
 class PropertyGroup implements \JsonSerializable
 {

lib/Widget/Definition/Rule.php

@@ -24,6 +24,7 @@
 
 /**
  * A rule to apply to a property
+ * @SWG\Definition()
  */
 class Rule implements \JsonSerializable
 {

lib/Widget/Definition/Stencil.php

@@ -23,6 +23,7 @@
 namespace Xibo\Widget\Definition;
 
 /**
+ * @SWG\Definition()
  * A Stencil is a template which is rendered in the server and/or client
  * it can optionally have properties and/or elements
  */