From e141ffd291c8928d6a65ad49e85c1e48f32241fa Mon Sep 17 00:00:00 2001 From: miholeus Date: Thu, 19 May 2016 14:28:32 +0300 Subject: [PATCH 1/3] added headers support --- Annotation/ApiDoc.php | 41 ++++++++++++++++++++++++++++++++ Resources/views/method.html.twig | 35 +++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php index 0b48c3b..863783c 100644 --- a/Annotation/ApiDoc.php +++ b/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; } diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig index 93a942f..0c75d6d 100644 --- a/Resources/views/method.html.twig +++ b/Resources/views/method.html.twig @@ -139,6 +139,29 @@ {% endif %} + + {% if data.headers is defined and data.headers is not empty %} +

Headers

+ + + + + + + + + + {% for name, infos in data.headers %} + + + + + + {% endfor %} + +
NameRequired?Description
{{ name }}{{ infos.required is defined and infos.required == 'true' ? 'true' : 'false'}}{{ infos.description is defined ? infos.description|trans : ''}}
+ {% endif %} + {% if data.parsedResponseMap is defined and data.parsedResponseMap is not empty %}

Return

@@ -282,6 +305,18 @@

{% endif %} + {% if data.headers is defined %} + + {% for name, infos in data.headers %} +

+ + = + - +

+ {% endfor %} + + {% endif %} +

= From d5c1c57cc907af098a6f4667000e2eb58f866bed Mon Sep 17 00:00:00 2001 From: miholeus Date: Thu, 19 May 2016 14:35:55 +0300 Subject: [PATCH 2/3] added headers documentation example --- Resources/doc/the-apidoc-annotation.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/Resources/doc/the-apidoc-annotation.rst b/Resources/doc/the-apidoc-annotation.rst index e4139b3..a5c7468 100644 --- a/Resources/doc/the-apidoc-annotation.rst +++ b/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 From 5123b49bf7c53eca54358e1e18697c1b321b53f4 Mon Sep 17 00:00:00 2001 From: miholeus Date: Thu, 19 May 2016 18:20:41 +0300 Subject: [PATCH 3/3] added tests for headers support --- Tests/Annotation/ApiDocTest.php | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Tests/Annotation/ApiDocTest.php b/Tests/Annotation/ApiDocTest.php index e52246c..c58d2d4 100644 --- a/Tests/Annotation/ApiDocTest.php +++ b/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(