Tests and Documentation for many undocumented features

ANNOTATIONS.md

@@ -183,4 +183,44 @@ of a custom class @var comments can be used with properties of that class.
 They will be used for validation and documentation. Supported child attributes
 are same as that of @param so they are documented under [@param](PARAM.md)
 
+
+## @format
+
+**Syntax:**
+
+    @format formatName
+
+**Example:**
+
+    @pformat HtmlFormat
+
+IF you want to force the request and or response format for a specific api method @format comment can be used
+
+
+## @view
+
+**Syntax:**
+
+    @view Name
+
+**Example:**
+
+    @view profile.twig 
+       
+Specify the view file to be loaded by HtmlFormat for the given api method as relative path from the `HtmlFormat::viewPath` and optionaly include the temmplate engine as the extension. When the extension is not specified it uses the `HtmlFormat::template` for finding the template engine
+
+
+## @errorView
+
+**Syntax:**
+
+    @errorView Name
+
+**Example:**
+
+    @errorView profile.twig
+        
+Similar to the `@view` but only used when an exception is thrown
+
+
 ---------------

FORMS.md

@@ -0,0 +1,22 @@
+# Forms
+
+Forms class generates html forms from http method and target url.
+
+Following attributes can be used for customizing the generated forms.
+
+> to be expanded soon!
+
+## @label
+## @field
+## @message
+## @form
+## @input
+## @textarea
+## @radio
+## @select
+## @submit
+## @fieldset
+
+
+
+

PARAM.md

@@ -117,6 +117,47 @@ exception
 Take a look at [MinMaxFix API Class](public/tests/param/MinMaxFix.php) and
 tests in [minmaxfix.feature](features/tests/param/minmaxfix.feature)
 
------------------------
 
-More to follow...
+## @pattern
+
+**Syntax:**
+
+    @param string $name [Description] {@pattern /REGEX_HERE/REGEX_OPTIONS}
+
+**Example:**
+
+    @param string $password at least one alpha and one numeric character
+    						{@pattern /^(?:[0-9]+[a-z]|[a-z]+[0-9])[a-z0-9]*$/i}
+
+Used by the validator to make sure the parammeter value matches the regex pattern. It uses preg_match for this verification. Please note that `/` should be used as the delimiter.
+
+Take a look at [MinMaxFix API Class](public/tests/param/Validation.php) and
+tests in [minmaxfix.feature](features/tests/param/validation.feature)
+
+## @message
+
+**Syntax:**
+
+    @param string|int|float $name [Description] {@message value}
+
+**Example:**
+
+    @param string $password Password 
+    						{@message Strong password with at least one alpha and one numeric character is required}
+
+Used by the validator to show a custom error message when invalid value is submitted. Use it to list the requirements for a parameter
+
+Take a look at [MinMaxFix API Class](public/tests/param/Validation.php) and
+tests in [minmaxfix.feature](features/tests/param/validation.feature)
+
+## @example
+
+**Syntax:**
+
+    @param string|int|float $name [Description] {@example value}
+
+**Example:**
+
+    @param string $name Name {@example Arul Kumaran}
+
+Used by the explorer to prefill the value for the parameter

features/bootstrap/RestContext.php

@@ -1,6 +1,7 @@
 <?php
 use Behat\Behat\Context\BehatContext;
 use Behat\Gherkin\Node\PyStringNode;
+use Luracast\Restler\Data\String;
 
 /**
  * Rest context.
@@ -48,16 +49,16 @@ public function __construct(array $parameters)
         $this->_client
             ->getEventDispatcher()
             ->addListener('request.error',
-            function (\Guzzle\Common\Event $event) {
-                switch ($event['response']->getStatusCode()) {
-                    case 400:
-                    case 401:
-                    case 404:
-                    case 405:
-                    case 406:
-                        $event->stopPropagation();
-                }
-            });
+                function (\Guzzle\Common\Event $event) {
+                    switch ($event['response']->getStatusCode()) {
+                        case 400:
+                        case 401:
+                        case 404:
+                        case 405:
+                        case 406:
+                            $event->stopPropagation();
+                    }
+                });
         $timezone = ini_get('date.timezone');
         if (empty($timezone))
             date_default_timezone_set('UTC');
@@ -102,10 +103,35 @@ public function thatISend($data)
      * @Given /^that I send:/
      * @param PyStringNode $data
      */
-    public function thatISendPyString(PyStringNode $data) {
+    public function thatISendPyString(PyStringNode $data)
+    {
         $this->thatISend($data);
     }
 
+    /**
+     * ============ json array ===================
+     * @Given /^the response contains (\[[^]]*\])$/
+     *
+     * ============ json object ==================
+     * @Given /^the response contains (\{(?>[^\{\}]+|(?1))*\})$/
+     *
+     * ============ json string ==================
+     * @Given /^the response contains ("[^"]*")$/
+     *
+     * ============ json int =====================
+     * @Given /^the response contains ([-+]?[0-9]*\.?[0-9]+)$/
+     *
+     * ============ json null or boolean =========
+     * @Given /^the response contains (null|true|false)$/
+     */
+    public function theResponseContains($response)
+    {
+        $data = json_encode($this->_data);
+        if (!String::contains($data, $response))
+            throw new Exception("Response value does not contain '$response' only\n\n"
+                . $this->echoLastResponse());
+    }
+
     /**
      * ============ json array ===================
      * @Given /^the response equals (\[[^]]*\])$/
@@ -127,7 +153,7 @@ public function theResponseEquals($response)
         $data = json_encode($this->_data);
         if ($data !== $response)
             throw new Exception("Response value does not match '$response'\n\n"
-            . $this->echoLastResponse());
+                . $this->echoLastResponse());
     }
 
     /**
@@ -138,6 +164,7 @@ public function theResponseEqualsPyString(PyStringNode $response)
     {
         $this->theResponseEquals($response);
     }
+
     /**
      * @Given /^that I want to make a new "([^"]*)"$/
      */
@@ -245,8 +272,8 @@ public function theRequestIsSentAsJson()
         $this->_headers['Content-Type'] = 'application/json; charset=utf-8';
         $this->_requestBody = json_encode(
             is_object($this->_restObject)
-            ? (array)$this->_restObject
-            : $this->_restObject
+                ? (array)$this->_restObject
+                : $this->_restObject
         );
     }
 
@@ -280,8 +307,8 @@ public function iRequest($pageUrl)
                     : $this->_restObject;
                 $this->_request = $this->_client
                     ->post($url, $this->_headers,
-                    (empty($this->_requestBody) ? $postFields :
-                        $this->_requestBody));
+                        (empty($this->_requestBody) ? $postFields :
+                            $this->_requestBody));
                 $this->_response = $this->_request->send();
                 break;
             case 'PUT' :
@@ -290,8 +317,8 @@ public function iRequest($pageUrl)
                     : $this->_restObject;
                 $this->_request = $this->_client
                     ->put($url, $this->_headers,
-                    (empty($this->_requestBody) ? $putFields :
-                        $this->_requestBody));
+                        (empty($this->_requestBody) ? $putFields :
+                            $this->_requestBody));
                 $this->_response = $this->_request->send();
                 break;
             case 'PATCH' :
@@ -300,8 +327,8 @@ public function iRequest($pageUrl)
                     : $this->_restObject;
                 $this->_request = $this->_client
                     ->patch($url, $this->_headers,
-                    (empty($this->_requestBody) ? $putFields :
-                        $this->_requestBody));
+                        (empty($this->_requestBody) ? $putFields :
+                            $this->_requestBody));
                 $this->_response = $this->_request->send();
                 break;
             case 'DELETE':

features/tests/param/validation.feature

@@ -0,0 +1,32 @@
+@param @type
+Feature: Validation
+
+  Scenario Outline: Valid Password
+    Given that I send {"password":<password>}
+    And the request is sent as JSON
+    When I request "/tests/param/validation/pattern"
+    Then the response status code should be 200
+    And the response is JSON
+    And the type is "string"
+    And the response equals <password>
+
+  Examples:
+    | password |
+    | "1a"     |
+    | "b2"     |
+    | "some1"  |
+
+  Scenario Outline: Invalid Password
+    Given that I send {"password":<password>}
+    And the request is sent as JSON
+    When I request "/tests/param/validation/pattern"
+    Then the response status code should be 400
+    And the response is JSON
+    And the type is "string"
+    And the response contains "Bad Request: Strong password with at least one alpha and one numeric character is required"
+
+  Examples:
+    | password   |
+    | "arul"     |
+    | "12345678" |
+    | "ONEtwo"   |

public/annotations.html

@@ -62,13 +62,31 @@ <h3>
                 <ul><li><a href="annotations.html#throws" title="Annotations - @throws">@throws</a></li></ul>
                 <ul><li><a href="annotations.html#return" title="Annotations - @return">@return</a></li></ul>
                 <ul><li><a href="annotations.html#var" title="Annotations - @var">@var</a></li></ul>
+                <ul><li><a href="annotations.html#format" title="Annotations - @format">@format</a></li></ul>
+                <ul><li><a href="annotations.html#view" title="Annotations - @view">@view</a></li></ul>
+                <ul><li><a href="annotations.html#errorview" title="Annotations - @errorView">@errorView</a></li></ul>
+            </li>
+            <li><a href="forms.html#forms" title="Forms">Forms</a>
+                <ul><li><a href="forms.html#label" title="Forms - @label">@label</a></li></ul>
+                <ul><li><a href="forms.html#field" title="Forms - @field">@field</a></li></ul>
+                <ul><li><a href="forms.html#message" title="Forms - @message">@message</a></li></ul>
+                <ul><li><a href="forms.html#form" title="Forms - @form">@form</a></li></ul>
+                <ul><li><a href="forms.html#input" title="Forms - @input">@input</a></li></ul>
+                <ul><li><a href="forms.html#textarea" title="Forms - @textarea">@textarea</a></li></ul>
+                <ul><li><a href="forms.html#radio" title="Forms - @radio">@radio</a></li></ul>
+                <ul><li><a href="forms.html#select" title="Forms - @select">@select</a></li></ul>
+                <ul><li><a href="forms.html#submit" title="Forms - @submit">@submit</a></li></ul>
+                <ul><li><a href="forms.html#fieldset" title="Forms - @fieldset">@fieldset</a></li></ul>
             </li>
             <li><a href="param.html#param-and--var" title="@param and @var">Param</a>
                 <ul><li><a href="param.html#from" title="Param - @from">@from</a></li></ul>
                 <ul><li><a href="param.html#type" title="Param - @type">@type</a></li></ul>
                 <ul><li><a href="param.html#choice" title="Param - @choice">@choice</a></li></ul>
                 <ul><li><a href="param.html#min----max" title="Param - @min & @max">@min & @max</a></li></ul>
                 <ul><li><a href="param.html#fix" title="Param - @fix">@fix</a></li></ul>
+                <ul><li><a href="param.html#pattern" title="Param - @pattern">@pattern</a></li></ul>
+                <ul><li><a href="param.html#message" title="Param - @message">@message</a></li></ul>
+                <ul><li><a href="param.html#example" title="Param - @example">@example</a></li></ul>
             </li>
 
         </ul>
@@ -297,6 +315,51 @@ <h2>@var</h2>
 They will be used for validation and documentation. Supported child attributes
 are same as that of @param so they are documented under <a href="param.html" target="_blank">@param</a></p>
 
+<p><a id="format" class="anchor"></a></p>
+<h2>@format</h2>
+
+<p><strong>Syntax:</strong></p>
+
+<pre><code>@format formatName
+</code></pre>
+
+<p><strong>Example:</strong></p>
+
+<pre><code>@pformat HtmlFormat
+</code></pre>
+
+<p>IF you want to force the request and or response format for a specific api method @format comment can be used</p>
+
+<p><a id="view" class="anchor"></a></p>
+<h2>@view</h2>
+
+<p><strong>Syntax:</strong></p>
+
+<pre><code>@view Name
+</code></pre>
+
+<p><strong>Example:</strong></p>
+
+<pre><code>@view profile.twig 
+</code></pre>
+
+<p>Specify the view file to be loaded by HtmlFormat for the given api method as relative path from the <code>HtmlFormat::viewPath</code> and optionaly include the temmplate engine as the extension. When the extension is not specified it uses the <code>HtmlFormat::template</code> for finding the template engine</p>
+
+<p><a id="errorview" class="anchor"></a></p>
+<h2>@errorView</h2>
+
+<p><strong>Syntax:</strong></p>
+
+<pre><code>@errorView Name
+</code></pre>
+
+<p><strong>Example:</strong></p>
+
+<pre><code>@errorView profile.twig
+</code></pre>
+
+<p>Similar to the <code>@view</code> but only used when an exception is thrown</p>
+
 <hr>
 
 </article>

public/examples/_003_multiformat/readme.html

@@ -266,7 +266,6 @@ <h3><a href="../index.html">Examples by Tag</a></h3>
 <p>This API Server exposes the following URIs</p>
 
 <pre><code>GET bmi ⇠ BMI::index()
-GET bmi ⇠ BMI::index()
 </code></pre>
 
 <p>Try the following links in your browser</p>

public/examples/_003_multiformat/readme.md

@@ -27,7 +27,6 @@ This BMI calculator service shows how you can serve data in different
 This API Server exposes the following URIs
 
     GET bmi ⇠ BMI::index()
-    GET bmi ⇠ BMI::index()
 
 
 

public/examples/_005_protected_api/readme.html

@@ -274,7 +274,6 @@ <h3><a href="../index.html">Examples by Tag</a></h3>
 GET restricted     ⇠ Simple::restricted()
 GET restricted2    ⇠ Simple::restricted2()
 GET secured        ⇠ Secured::index()
-GET secured        ⇠ Secured::index()
 GET simpleauth/key ⇠ SimpleAuth::key()
 </code></pre>