Added status codes

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;
     }
 }

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:

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 %}

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);
+        }
+    }
 }