Input params and handlers

* Split InputParam to multiple subclasses
* Added attributes to parameters and handlers

Author: lulco

CHANGELOG.md

@@ -8,9 +8,19 @@ Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) princip
 
 * Update nette libs to version 3.0.0 (BC break)
 * Added typehints (BC break)
+* Splitted InputParam to multiple subclasses (BC break)
+* Removed type TYPE_POST_JSON_KEY (BC break)
+* Wrong input now returns code 400 instead of 500 (BC break if somebody checks return code)
 * Pretty JSON output in API console - without escaping unicode and slashes
 * Replaced handler information array triplet (endpoint, handler, authorization) with Api
 
+#### Added
+
+* Added type JsonInputParam with scheme as replacement for type TYPE_POST_JSON_KEY
+* Detailed error for wrong input if debugger is enabled
+* Added summary (short description), description, tags and deprecated flag for API handlers
+* Added description, default value and example for input params
+
 #### Removed
 
 * Removed support for PHP 5.6, 7.0 and hhvm (BC Break)

README.md

@@ -55,9 +55,9 @@ services:
   - Tomaj\NetteApi\Misc\IpDetector
   apiDecider:
     factory: Tomaj\NetteApi\ApiDecider
-      setup:
-        - addApi(\Tomaj\NetteApi\EndpointIdentifier('GET', 1, 'users'), \App\MyApi\v1\Handlers\UsersListingHandler(), \Tomaj\NetteApi\Authorization\NoAuthorization())
-        - addApi(\Tomaj\NetteApi\EndpointIdentifier('POST', 1, 'users', 'send-email'), \App\MyApi\v1\Handlers\SendEmailHandler(), \Tomaj\NetteApi\Authorization\BearerTokenAuthorization())
+    setup:
+      - addApi(\Tomaj\NetteApi\EndpointIdentifier('GET', 1, 'users'), \App\MyApi\v1\Handlers\UsersListingHandler(), \Tomaj\NetteApi\Authorization\NoAuthorization())
+      - addApi(\Tomaj\NetteApi\EndpointIdentifier('POST', 1, 'users', 'send-email'), \App\MyApi\v1\Handlers\SendEmailHandler(), \Tomaj\NetteApi\Authorization\BearerTokenAuthorization())
 ```
 
 As you can see in example, you can register as many endpoints as you want with different configurations. Nette-Api supports API versioning from the beginning.
@@ -179,8 +179,8 @@ Example with user detail:
 namespace App\MyApi\v1\Handlers;
 
 use Tomaj\NetteApi\Handlers\BaseHandler;
+use Tomaj\NetteApi\Params\GetInputParam;
 use Tomaj\NetteApi\Response\JsonApiResponse;
-use Tomaj\NetteApi\Params\InputParam;
 use Tomaj\NetteApi\Response\ResponseInterface;
 
 class UsersDetailHandler extends Basehandler
@@ -196,7 +196,7 @@ class UsersDetailHandler extends Basehandler
     public function params(): array
     {
         return [
-            new InputParam(InputParam::TYPE_GET, 'id', InputParam::REQUIRED),
+            (new GetInputParam('id'))->setRequired(),
         ];
     }
 
@@ -224,12 +224,12 @@ This is table with support input types:
 
 | Input type      | Example
 | ----------      | -------
-| POST            | `new InputParam(InputParam::TYPE_POST, 'key')`
-| GET             | `new InputParam(InputParam::TYPE_GET, 'key')`
-| FILE            | `new InputParam(InputParam::TYPE_FILE, 'key')`
-| COOKIE          | `new InputParam(InputParam::TYPE_COOKIE, 'key')`
-| RAW POST        | `new InputParam(InputParam::TYPE_POST_RAW, 'key')`
-| JSON            | `new InputParam(InputParam::TYPE_POST_JSON_KEY, 'key')`
+| POST            | `new PostInputParam('key')`
+| GET             | `new GetInputParam('key')`
+| FILE            | `new FileInputParam('key')`
+| COOKIE          | `new CookieInputParam('key')`
+| RAW POST        | `new RawInputParam('key')`
+| JSON            | `new JsonInputParam('key', '{"type": "object"}')`
 
 
 ## Security

UPGRADE.md

@@ -2,6 +2,35 @@
 
 ## Upgrade from 1.x to 2.0.0
 
+### Splitted InputParam to multiple subclasses
+InputParam is now abstract class and all types have their own class. Also InputParam is more like Nette Form inputs with fluent API
+
+Examples of replacements:
+
+Requred get input with available values:
+
+Old:
+```php
+new InputParam(InputParam::TYPE_GET, 'status', InputParam::REQUIRED, ['ok', 'error'])
+```
+
+New:
+```php
+(new GetInputParam('status'))->setRequired()->setAvailableValues(['ok', 'error'])
+```
+
+Multiple optional file input:
+
+Old:
+```php
+new InputParam(InputParam::TYPE_FILE, 'myfile', InputParam::OPTIONAL, null, true)
+```
+
+New:
+```php
+(new FileInputParam('myfile'))->setMulti()
+```
+
 ### Removed support for old PHP versions
 New version not supported PHP versions 5.6 and 7.0 and also hhvm. Please use it with newer versions of PHP (>7.1)
 
@@ -47,6 +76,9 @@ Add typehints to methods:
 - `getApiAction(): ?string`
 - `getUrl(): string`
 
+### Changed behavior
+API handler tripplet (array of endpoint, handler, authorization) has been changed to class `Api` which has methods `getEndpoint()`, `getHandler()` and `getAuthorization()`.
+
 ### Renamed methods
 Few methods have been renamed, please use their new versions:
 - `ApiDecider::addApiHandler()` -> `ApiDecider::addApi()`
@@ -62,7 +94,7 @@ BaseHandler now have few final methods:
 
 ### Removed params
 Parameters $parent and $name have been removed from ApiListingControl. New usage is:
-```
+```php
 new ApiListingControl($apiDecider)
 ```
 
@@ -75,8 +107,13 @@ Some parameters were strictly typed:
 ### Changed events
 Registration of event onClick in ApiListingControl.
 Use:
-```
+```php
 $apiListing->onClick[] = function ($method, $version, $package, $apiAction) {
     ...
 };
 ```
+
+### Features
+With new version of Nette API you can:
+- add description for your API handlers, also you can mark some handlers as deprecated and add tags for them.
+- add description, default value and example for all your input params

composer.json

@@ -20,7 +20,8 @@
         "nette/http": "^3.0",
         "tracy/tracy": "^2.6",
         "league/fractal": "^0.17.0",
-        "tomaj/nette-bootstrap-form": "^2.0"
+        "tomaj/nette-bootstrap-form": "^2.0",
+        "justinrainbow/json-schema": "^5.2"
     },
     "require-dev": {
         "nette/di": "^3.0",

src/Component/ApiConsoleControl.php

@@ -13,7 +13,6 @@
 use Tomaj\NetteApi\EndpointInterface;
 use Tomaj\NetteApi\Handlers\ApiHandlerInterface;
 use Tomaj\NetteApi\Misc\ConsoleRequest;
-use Tomaj\NetteApi\Params\InputParam;
 
 class ApiConsoleControl extends Control
 {
@@ -36,6 +35,7 @@ public function __construct(IRequest $request, EndpointInterface $endpoint, ApiH
     public function render(): void
     {
         $this->getTemplate()->setFile(__DIR__ . '/console.latte');
+        $this->getTemplate()->add('handler', $this->handler);
         $this->getTemplate()->render();
     }
 
@@ -66,7 +66,7 @@ protected function createComponentConsoleForm(): Form
 
         if ($this->authorization instanceof BearerTokenAuthorization) {
             $form->addText('token', 'Token')
-                ->setAttribute('placeholder', 'Enter token');
+                ->setHtmlAttribute('placeholder', 'Enter token');
         } elseif ($this->authorization instanceof NoAuthorization) {
             $form->addText('authorization', 'Authorization')
                 ->setDisabled(true);
@@ -76,45 +76,11 @@ protected function createComponentConsoleForm(): Form
         $form->addCheckbox('send_session_id', 'Send session id cookie');
 
         $params = $this->handler->params();
-        $jsonField = null;
-        $jsonParams = [];
         foreach ($params as $param) {
-            $count = $param->isMulti() ? 5 : 1;
-            for ($i = 0; $i < $count; $i++) {
-                $key = $param->getKey();
-                if ($param->isMulti()) {
-                    $key = $key . '___' . $i;
-                }
-
-                if ($param->getAvailableValues() && is_array($param->getAvailableValues())) {
-                    $c = $form->addSelect($key, $this->getParamLabel($param), array_combine($param->getAvailableValues(), $param->getAvailableValues()));
-                    if (!$param->isRequired()) {
-                        $c->setPrompt('Select ' . $this->getLabel($param));
-                    }
-                } elseif ($param->getAvailableValues() && is_string($param->getAvailableValues())) {
-                    $c = $form->addText($key, $this->getParamLabel($param))->setDisabled(true);
-                    $defaults[$key] = $param->getAvailableValues();
-                } elseif ($param->getType() == InputParam::TYPE_FILE) {
-                    $c = $form->addUpload($key, $this->getParamLabel($param));
-                } elseif ($param->getType() == InputParam::TYPE_POST_RAW) {
-                    $c = $form->addTextArea('post_raw', $this->getParamLabel($param))
-                        ->setAttribute('rows', 10);
-                } elseif ($param->getType() == InputParam::TYPE_POST_JSON_KEY) {
-                    if ($jsonField === null) {
-                        $jsonField = $form->addTextArea('post_raw', 'JSON')
-                            ->setOption('description', 'Empty string means "key is required", null means "key is optional"');
-                    }
-                    $jsonParams[$key] = $param->isRequired() ? '' : null;
-                } else {
-                    $c = $form->addText($key, $this->getParamLabel($param));
-                }
-            }
-        }
-        if ($jsonField !== null && $jsonParams) {
-            $jsonField->setDefaultValue(json_encode($jsonParams, JSON_PRETTY_PRINT));
+            $param->updateConsoleForm($form);
         }
 
-        $form->addSubmit('send', 'Otestuj')
+        $form->addSubmit('send', 'Try api')
             ->getControlPrototype()
             ->setName('button')
             ->setHtml('<i class="fa fa-cloud-upload"></i> Try api');
@@ -125,21 +91,6 @@ protected function createComponentConsoleForm(): Form
         return $form;
     }
 
-    private function getLabel(InputParam $param): string
-    {
-        return ucfirst(str_replace('_', ' ', $param->getKey()));
-    }
-
-    private function getParamLabel(InputParam $param): string
-    {
-        $title = $this->getLabel($param);
-        if ($param->isRequired()) {
-            $title .= ' *';
-        }
-        $title .= ' (' . $param->getType() . ')';
-        return $title;
-    }
-
     public function formSucceeded(Form $form, ArrayHash $values): void
     {
         $url = $values['api_url'];

src/Component/api_listing.latte

@@ -1,5 +1,13 @@
 <div class="api-listing">
     <div n:foreach="$apis as $version => $versionApis" class="listing-verions listing-version-{$version}">
+        {php $showSummary = false}
+        {foreach $versionApis as $api}
+            {if $api->getHandler()->summary()}
+                {php $showSummary = true}
+                {breakIf true}
+            {/if}
+        {/foreach}
+
         <h3>Version {$version}</h3>
 
         <div class="table-responsive">
@@ -9,16 +17,20 @@
                         <th>Method</th>
                         <th>Url</th>
                         <th>Handler</th>
+                        <th n:if="$showSummary">Summary</th>
                         <th>Authorization</th>
                     </tr>
                 </thead>
                 <tbody>
                     <tr n:foreach="$versionApis as $api">
                         <td><span class="label label-default">{$api->getEndpoint()->getMethod()}</span></td>
                         <td>
-                            <a href="{link Select! $api->getEndpoint()->getMethod(), $api->getEndpoint()->getVersion(), $api->getEndpoint()->getPackage(), $api->getEndpoint()->getApiAction()}"><b>/{$api->getEndpoint()->getUrl()}</b></a>
+                            <s n:tag-if="$api->getHandler()->deprecated()" title="Deprecated">
+                                <a href="{link Select! $api->getEndpoint()->getMethod(), $api->getEndpoint()->getVersion(), $api->getEndpoint()->getPackage(), $api->getEndpoint()->getApiAction()}"><b>/{$api->getEndpoint()->getUrl()}</b></a>
+                            </s>
                         </td>
                         <td>{get_class($api->getHandler())}</td>
+                        <td n:if="$showSummary">{$api->getHandler()->summary()}</td>
                         <td>{get_class($api->getAuthorization())}</td>
                     </tr>
                 </tbody>

src/Component/console.latte

@@ -1,6 +1,11 @@
-
 <h2>Api Web Console</h2>
 
+<div n:if="$handler->description() || $handler->deprecated() || $handler->tags()">
+    <span n:if="$handler->deprecated()" class="btn btn-sm btn-danger">API is deprecated</span>
+    <span n:foreach="$handler->tags() as $tag" class="btn btn-sm btn-primary">{$tag}</span>
+    <p n:if="$handler->description()">{$handler->description()}</p>
+</div>
+
 {ifset $response}
     <div class="row">
         <div class="col-md-12">

src/Handlers/ApiHandlerInterface.php

@@ -3,18 +3,42 @@
 namespace Tomaj\NetteApi\Handlers;
 
 use Tomaj\NetteApi\EndpointInterface;
-use Tomaj\NetteApi\Params\InputParam;
+use Tomaj\NetteApi\Params\ParamInterface;
 use Tomaj\NetteApi\Response\ResponseInterface;
 
 interface ApiHandlerInterface
 {
+    /**
+     * Summary of handler - short description of handler
+     * @return string
+     */
+    public function summary(): string;
+
+    /**
+     * Description of handler
+     * @return string
+     */
+    public function description(): string;
+
     /**
      * Returns available parameters that handler need
      *
-     * @return InputParam[]
+     * @return ParamInterface[]
      */
     public function params(): array;
 
+    /**
+     * Returns list of tags for handler
+     * @return array
+     */
+    public function tags(): array;
+
+    /**
+     * Marks handler as deprecated
+     * @return bool
+     */
+    public function deprecated(): bool;
+
     /**
      * Main handle method that will be executed when api
      * endpoint contected with this handler will be triggered

src/Handlers/BaseHandler.php

@@ -32,6 +32,22 @@ public function __construct(ScopeFactoryInterface $scopeFactory = null)
         $this->fractal = new Manager($scopeFactory);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function summary(): string
+    {
+        return '';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function description(): string
+    {
+        return '';
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -40,10 +56,26 @@ public function params(): array
         return [];
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function tags(): array
+    {
+        return [];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function deprecated(): bool
+    {
+        return false;
+    }
+
     protected function getFractal(): Manager
     {
         if (!$this->fractal) {
-            throw new InvalidStateException("Fractal manager isnt initialized. Did you call parent::__construct() in your handler constructor?");
+            throw new InvalidStateException("Fractal manager isn't initialized. Did you call parent::__construct() in your handler constructor?");
         }
         return $this->fractal;
     }