Merge pull request #853 from miholeus/master

Headers support

Annotation/ApiDoc.php

@@ -47,6 +47,12 @@ class ApiDoc
      * @var array
      */
     private $parameters = array();
+    /**
+     * Headers that client can send.
+     *
+     * @var array
+     */
+    private $headers = array();
 
     /**
      * @var string
@@ -230,6 +236,19 @@ class ApiDoc
             }
         }
 
+        if (isset($data['headers'])) {
+            foreach ($data['headers'] as $header) {
+                if (!isset($header['name'])) {
+                    throw new \InvalidArgumentException('A "header" element has to contain a "name" attribute');
+                }
+
+                $name = $header['name'];
+                unset($header['name']);
+
+                $this->addHeader($name, $header);
+            }
+        }
+
         if (isset($data['output'])) {
             $this->output = $data['output'];
         }
@@ -457,6 +476,15 @@ class ApiDoc
         $this->parameters = $parameters;
     }
 
+    /**
+     * @param $name
+     * @param array $header
+     */
+    public function addHeader($name, array $header)
+    {
+        $this->headers[$name] = $header;
+    }
+
     /**
      * Sets the response data as processed by the parsers - same format as parameters
      *
@@ -611,8 +639,17 @@ class ApiDoc
         return $this->parameters;
     }
 
+    /**
+     * @return array
+     */
+    public function getHeaders()
+    {
+        return $this->headers;
+    }
+
     /**
      * @param boolean $deprecated
+     * @return $this
      */
     public function setDeprecated($deprecated)
     {
@@ -663,6 +700,10 @@ class ApiDoc
             $data['parameters'] = $parameters;
         }
 
+        if ($headers = $this->headers) {
+            $data['headers'] = $headers;
+        }
+
         if ($requirements = $this->requirements) {
             $data['requirements'] = $requirements;
         }

Resources/doc/the-apidoc-annotation.rst

@@ -93,6 +93,28 @@ The following properties are available:
 * ``filters``: an array of filters;
 * ``requirements``: an array of requirements;
 * ``parameters``: an array of parameters;
+* ``headers``: an array of headers; available properties are: ``name``, ``description``, ``required``, ``default``. Example:
+
+.. code-block:: php
+
+    class YourController
+    {
+        /**
+         * @ApiDoc(
+         *     headers={
+         *         {
+         *             "name"="X-AUTHORIZE-KEY",
+         *             "description"="Authorization key"
+         *         }
+         *     }
+         * )
+         */
+        public function myFunction()
+        {
+            // ...
+        }
+    }
+
 * ``input``: the input type associated to the method (currently this supports
   Form Types, classes with JMS Serializer metadata, classes with Validation
   component metadata and classes that implement JsonSerializable) useful for

Resources/views/method.html.twig

@@ -139,6 +139,29 @@
                 </table>
             {% endif %}
 
+
+            {% if data.headers is defined and data.headers is not empty %}
+                <h4>Headers</h4>
+                <table class="fullwidth">
+                    <thead>
+                    <tr>
+                        <th>Name</th>
+                        <th>Required?</th>
+                        <th>Description</th>
+                    </tr>
+                    </thead>
+                    <tbody>
+                    {% for name, infos in data.headers %}
+                        <tr>
+                            <td>{{ name }}</td>
+                            <td>{{ infos.required is defined and infos.required == 'true' ? 'true' : 'false'}}</td>
+                            <td>{{ infos.description is defined ? infos.description|trans : ''}}</td>
+                        </tr>
+                    {% endfor %}
+                    </tbody>
+                </table>
+            {% endif %}
+
             {% if data.parsedResponseMap is defined and data.parsedResponseMap is not empty %}
                 <h4>Return</h4>
                 <table class='fullwidth'>
@@ -282,6 +305,18 @@
                                     </p>
                                 {% endif %}
 
+                                {% if data.headers is defined %}
+
+                                    {% for name, infos in data.headers %}
+                                        <p class="tuple">
+                                            <input type="text" class="key" value="{{ name }}" />
+                                            <span>=</span>
+                                            <input type="text" class="value" value="{% if infos.default is defined %}{{ infos.default }}{% endif %}" placeholder="Value" /> <span class="remove">-</span>
+                                        </p>
+                                    {% endfor %}
+
+                                {% endif %}
+
                                 <p class="tuple">
                                     <input type="text" class="key" placeholder="Key" />
                                     <span>=</span>

Tests/Annotation/ApiDocTest.php

@@ -34,6 +34,7 @@ class ApiDocTest extends TestCase
         $this->assertFalse(isset($array['parameters']));
         $this->assertNull($annot->getInput());
         $this->assertFalse($array['authentication']);
+        $this->assertFalse(isset($array['headers']));
         $this->assertTrue(is_array($array['authenticationRoles']));
     }
 
@@ -291,6 +292,28 @@ class ApiDocTest extends TestCase
         $this->assertTrue(isset($array['parameters']['fooId']['dataType']));
     }
 
+    public function testConstructWithHeaders()
+    {
+        $data = array(
+            'headers' => array(
+                array(
+                    'name' => 'headerName',
+                    'description' => 'Some description'
+                )
+            )
+        );
+
+        $annot = new ApiDoc($data);
+        $array = $annot->toArray();
+
+        $this->assertArrayHasKey('headerName', $array['headers']);
+        $this->assertNotEmpty($array['headers']['headerName']);
+
+        $keys = array_keys($array['headers']);
+        $this->assertEquals($data['headers'][0]['name'], $keys[0]);
+        $this->assertEquals($data['headers'][0]['description'], $array['headers']['headerName']['description']);
+    }
+
     public function testConstructWithOneTag()
     {
         $data = array(