Merge pull request #70 from evillemez/apidoc_return

Implemented @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) {

Formatter/MarkdownFormatter.php

@@ -85,6 +85,22 @@ class MarkdownFormatter extends AbstractFormatter
             }
         }
 
+        if (isset($data['response'])) {
+            $markdown .= "#### Response ####\n\n";
+
+            foreach ($data['response'] as $name => $parameter) {
+                $markdown .= sprintf("%s:\n\n", $name);
+                $markdown .= sprintf("  * type: %s\n", $parameter['dataType']);
+                $markdown .= sprintf("  * required: %s\n", $parameter['required'] ? 'true' : 'false');
+
+                if (isset($parameter['description']) && !empty($parameter['description'])) {
+                    $markdown .= sprintf("  * description: %s\n", $parameter['description']);
+                }
+
+                $markdown .= "\n";
+            }
+        }
+
         return $markdown;
     }
 

Parser/JmsMetadataParser.php

@@ -81,7 +81,6 @@ class JmsMetadataParser implements ParserInterface
 
         //TODO: regex comment to get description - or move doc comment parsing functionality from `ApiDocExtractor` to a new location
         //in order to reuse it here
-        
         return $description;
     }
 

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="dependency_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/MarkdownFormatterTest.php

@@ -186,6 +186,19 @@ arr:
   * description: No description.
 
 
+### `GET` /jms-return-test ###
+
+_Testing return_
+
+#### Response ####
+
+a:
+
+  * type: string
+  * required: true
+  * description: A nice description
+
+
 ### `ANY` /my-commented/{id}/{page} ###
 
 _This method is useful to test if the getDocComment works._

Tests/Formatter/SimpleFormatterTest.php

@@ -215,6 +215,20 @@ class SimpleFormatterTest extends WebTestCase
                     'description' => 'Testing JMS'
                 ),
                 4 =>
+                array(
+                    'method' => 'GET',
+                    'uri' => '/jms-return-test',
+                    'description' => 'Testing return',
+                    'response' => array(
+                        'a' => array(
+                            'dataType' => 'string',
+                            'required' => true,
+                            'description' => 'A nice description',
+                            'readonly' => false
+                        )
+                    )
+                ),
+                5 =>
                 array(
                     'method' => 'ANY',
                     'uri' => '/my-commented/{id}/{page}',
@@ -226,7 +240,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 +249,7 @@ class SimpleFormatterTest extends WebTestCase
                         'id' => array('type' => '', 'description' => '', 'requirement' => '\d+')
                     ),
                 ),
-                6 =>
+                7 =>
                 array(
                     'method' => 'GET',
                     'uri' => '/z-action-with-query-param',