working on apidoc return property

Annotation/ApiDoc.php

@@ -28,6 +28,11 @@ class ApiDoc
      */
     private $input = null;
     
+    /**
+     * @var string
+     */
+    private $return = null;
+
     /**
      * @var string
      */
@@ -63,6 +68,11 @@ class ApiDoc
      */
     private $parameters = array();
     
+    /**
+     * @var array
+     */
+    private $response = array();
+
     /**
      * @var Route
      */
@@ -89,6 +99,10 @@ class ApiDoc
             $this->description = $data['description'];
         }
         
+        if (isset($data['return'])) {
+            $this->return = $data['return'];
+        }
+
         $this->isResource = isset($data['resource']) && $data['resource'];
     }
 
@@ -126,6 +140,14 @@ class ApiDoc
         return $this->input;
     }
 
+    /**
+     * @return string|null
+     */
+    public function getReturn()
+    {
+        return $this->return;
+    }
+
     /**
      * @return string
      */
@@ -182,6 +204,24 @@ class ApiDoc
         $this->parameters = $parameters;
     }
     
+    /**
+     * Sets the responsed data as processed by the parsers - same format as parameters
+     *
+     * @param array $response
+     */
+    public function setResponse(array $response)
+    {
+        $this->response = $response;
+    }
+    
+    /**
+     * @return array
+     */
+    public function getResponse()
+    {
+        return $this->response;
+    }
+
     /**
      * @param Route $route
      */
@@ -228,6 +268,10 @@ class ApiDoc
             $data['requirements'] = $requirements;
         }
         
+        if ($response = $this->response) {
+            $data['response'] = $response;
+        }
+
         return $data;
     }
 }

Extractor/ApiDocExtractor.php

@@ -223,7 +223,7 @@ class ApiDocExtractor
         // doc
         $annotation->setDocumentation($this->getDocCommentText($method));
 
-        // input
+        // input (populates 'parameters' for the formatters)
         if (null !== $input = $annotation->getInput()) {
             $parameters = array();
 
@@ -244,6 +244,20 @@ class ApiDocExtractor
             $annotation->setParameters($parameters);
         }
 
+        // return (populates 'response' for the formatters)
+        if (null !== $return = $annotation->getReturn()) {
+            $response = array();
+            
+            foreach ($this->parsers as $parser) {
+                if ($parser->supports($return)) {
+                    $response = $parser->parse($return);
+                    break;
+                }
+            }
+            
+            $annotation->setResponse($response);
+        }
+
         // requirements
         $requirements = array();
         foreach ($route->getRequirements() as $name => $value) {

Tests/Extractor/ApiDocExtratorTest.php

@@ -22,7 +22,7 @@ class ApiDocExtractorTest extends WebTestCase
         $data = $extractor->all();
 
         $this->assertTrue(is_array($data));
-        $this->assertCount(11, $data);
+        $this->assertCount(12, $data);
 
         foreach ($data as $d) {
             $this->assertTrue(is_array($d));

Tests/Fixtures/Controller/TestController.php

@@ -100,4 +100,15 @@ class TestController
     public function jmsInputTestAction()
     {
     }
+
+    /**
+     * @ApiDoc(
+     *  description="Testing return",
+     *  return="test_type"
+     * )
+     */
+    public function jmsReturnTestAction()
+    {
+    }
+
 }

Tests/Fixtures/app/config/routing.yml

@@ -46,6 +46,12 @@ test_route_9:
     requirements:
         _method: POST
 
+test_route_10:
+    pattern: /jms-return-test
+    defaults: { _controller: NelmioApiDocTestBundle:Test:jmsReturnTest }
+    requirements:
+        _method: GET
+
 test_service_route_1:
     pattern:  /tests.{_format}
     defaults: { _controller: nemlio.test.controller:indexAction, _format: json }

Tests/Formatter/SimpleFormatterTest.php

@@ -215,6 +215,15 @@ class SimpleFormatterTest extends WebTestCase
                     'description' => 'Testing JMS'
                 ),
                 4 =>
+                array(
+                    'method' => 'GET',
+                    'uri' => '/jms-return-test',
+                    'description' => 'Testing return',
+                    'response' => array(
+                        
+                    )
+                ),
+                5 =>
                 array(
                     'method' => 'ANY',
                     'uri' => '/my-commented/{id}/{page}',
@@ -226,7 +235,7 @@ class SimpleFormatterTest extends WebTestCase
                     'description' => 'This method is useful to test if the getDocComment works.',
                     'documentation' => "This method is useful to test if the getDocComment works.\nAnd, it supports multilines until the first '@' char."
                 ),
-                5 =>
+                6 =>
                 array(
                     'method' => 'ANY',
                     'uri' => '/yet-another/{id}',
@@ -235,7 +244,7 @@ class SimpleFormatterTest extends WebTestCase
                         'id' => array('type' => '', 'description' => '', 'requirement' => '\d+')
                     ),
                 ),
-                6 =>
+                7 =>
                 array(
                     'method' => 'GET',
                     'uri' => '/z-action-with-query-param',