From 742e53b99beee42702d5a32366f6d2a1ac1f304b Mon Sep 17 00:00:00 2001
From: Baldur Rensch <baldur.rensch@hautelook.com>
Date: Tue, 13 Nov 2012 04:45:07 +0000
Subject: [PATCH 1/2] Added status codes

---
 Annotation/ApiDoc.php            | 29 +++++++++++++++++++++++++++++
 README.md                        | 25 +++++++++++++++++++++++--
 Resources/views/method.html.twig | 21 +++++++++++++++++++++
 Tests/Annotation/ApiDocTest.php  | 20 ++++++++++++++++++++
 4 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php
index c06eec7..f9fe6d2 100644
--- a/Annotation/ApiDoc.php
+++ b/Annotation/ApiDoc.php
@@ -78,6 +78,11 @@ class ApiDoc
      */
     private $route;
 
+    /**
+     * @var array
+     */
+    private $statusCodes = array();
+
     public function __construct(array $data)
     {
         if (isset($data['input'])) {
@@ -103,6 +108,10 @@ class ApiDoc
             $this->return = $data['return'];
         }
 
+        if (isset($data['statusCodes'])) {
+            $this->statusCodes = $data['statusCodes'];
+        }
+
         $this->isResource = isset($data['resource']) && $data['resource'];
     }
 
@@ -238,6 +247,22 @@ class ApiDoc
         return $this->route;
     }
 
+    /**
+     * @return array
+     */
+    public function getStatusCodes()
+    {
+        return $this->statusCodes;
+    }
+
+    /**
+     * @param array $codes
+     */
+    public function addStatusCodes($codes)
+    {
+        $this->statusCodes = array_merge($this->statusCodes, $codes);
+    }
+
     /**
      * @return array
      */
@@ -272,6 +297,10 @@ class ApiDoc
             $data['response'] = $response;
         }
 
+        if ($statusCodes = $this->statusCodes) {
+            $data['statusCodes'] = $statusCodes;
+        }
+
         return $data;
     }
 }
diff --git a/README.md b/README.md
index 451d7c6..808349f 100644
--- a/README.md
+++ b/README.md
@@ -102,9 +102,30 @@ The following properties are available:
 
 * `input`: the input type associated to the method, currently this supports Form Types, and classes with JMS Serializer
  metadata, useful for POST|PUT methods, either as FQCN or as form type (if it is registered in the form factory in the container)
- 
+
 * `return`: the return type associated with the response.  Specified and parsed the same way as `input`.
 
+* `statusCodes`: an array of HTTP status codes and a description of when that status is returned; Example:
+
+``` php
+<?php
+
+class YourController
+{
+    /**
+     * @ApiDoc(
+     *     statusCodes={
+     *         200="Returned when successful",
+     *         403="Returned when the user is not authorized to say hello"},
+     * )
+     */
+    public function myFunction()
+    {
+        // ...
+    }
+}
+```
+
 Each _filter_ has to define a `name` parameter, but other parameters are free. Filters are often optional
 parameters, and you can document them as you want, but keep in mind to be consistent for the whole documentation.
 
@@ -191,7 +212,7 @@ configure this sandbox using the following parameters:
 
 The bundle provides a way to register multiple `input` parsers.  The first parser that can handle the specified
 input is used, so you can configure their priorities via container tags.  Here's an example parser service registration:
-    
+
     #app/config/config.yml
     services:
         mybundle.api_doc.extractor.custom_parser:
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index a7607a2..ae9f4f1 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -130,6 +130,27 @@
                     </tbody>
                 </table>
             {% endif %}
+
+             {% if data.statusCodes is defined and data.statusCodes is not empty %}
+            <h4>Status Codes</h4>
+            <table class="fullwidth">
+                <thead>
+                    <tr>
+                        <th>Status Code</th>
+                        <th>Description</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    {% for status_code, description in data.statusCodes %}
+                    <tr>
+                        <td><a href="http://en.wikipedia.org/wiki/HTTP_{{ status_code }}" target="_blank">{{ status_code }}<a/></td>
+                        <td>{{ description }}</td>
+                    </tr>
+                    {% endfor %}
+                </tbody>
+            </table>
+            {% endif %}
+
             </div>
 
             {% if enableSandbox %}
diff --git a/Tests/Annotation/ApiDocTest.php b/Tests/Annotation/ApiDocTest.php
index d8f3212..c03b280 100644
--- a/Tests/Annotation/ApiDocTest.php
+++ b/Tests/Annotation/ApiDocTest.php
@@ -173,4 +173,24 @@ class ApiDocTest extends TestCase
         $this->assertEquals($data['description'], $array['description']);
         $this->assertEquals($data['input'], $annot->getInput());
     }
+
+    public function testConstructWithHTTPResponseCodes()
+    {
+        $data = array(
+            'description' => 'Heya',
+            'statusCodes' => array(
+                200 => "Returned when successful",
+                403 => "Returned when the user is not authorized"
+            )
+        );
+
+        $annot = new ApiDoc($data);
+        $array = $annot->toArray();
+
+        $this->assertTrue(is_array($array));
+        $this->assertTrue(is_array($array['statusCodes']));
+        foreach ($data['statusCodes'] as $code => $message) {
+            $this->assertEquals($array['statusCodes'][$code], $message);
+        }
+    }
 }

From cd45f4b1469034675b410f3bb599d831ad33409d Mon Sep 17 00:00:00 2001
From: Baldur Rensch <baldur.rensch@hautelook.com>
Date: Tue, 13 Nov 2012 08:04:04 -0800
Subject: [PATCH 2/2] Removed unused function

---
 Annotation/ApiDoc.php | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php
index f9fe6d2..f7ee000 100644
--- a/Annotation/ApiDoc.php
+++ b/Annotation/ApiDoc.php
@@ -255,14 +255,6 @@ class ApiDoc
         return $this->statusCodes;
     }
 
-    /**
-     * @param array $codes
-     */
-    public function addStatusCodes($codes)
-    {
-        $this->statusCodes = array_merge($this->statusCodes, $codes);
-    }
-
     /**
      * @return array
      */