diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php index 1c9c9d0..c06eec7 100644 --- a/Annotation/ApiDoc.php +++ b/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; } } diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 6eb028f..7dfee71 100644 --- a/Extractor/ApiDocExtractor.php +++ b/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) { diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php index 06befaa..3126909 100644 --- a/Formatter/MarkdownFormatter.php +++ b/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; } diff --git a/Parser/JmsMetadataParser.php b/Parser/JmsMetadataParser.php index 34535bf..41ac909 100644 --- a/Parser/JmsMetadataParser.php +++ b/Parser/JmsMetadataParser.php @@ -35,10 +35,10 @@ class JmsMetadataParser implements ParserInterface try { if ($meta = $this->factory->getMetadataForClass($input)) { return true; - } + } } catch (\ReflectionException $e) { } - + return false; } @@ -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; } diff --git a/Tests/Extractor/ApiDocExtratorTest.php b/Tests/Extractor/ApiDocExtratorTest.php index a15de3a..700c01e 100644 --- a/Tests/Extractor/ApiDocExtratorTest.php +++ b/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)); diff --git a/Tests/Fixtures/Controller/TestController.php b/Tests/Fixtures/Controller/TestController.php index 16c8e04..542b7c8 100644 --- a/Tests/Fixtures/Controller/TestController.php +++ b/Tests/Fixtures/Controller/TestController.php @@ -100,4 +100,15 @@ class TestController public function jmsInputTestAction() { } + + /** + * @ApiDoc( + * description="Testing return", + * return="dependency_type" + * ) + */ + public function jmsReturnTestAction() + { + } + } diff --git a/Tests/Fixtures/app/config/routing.yml b/Tests/Fixtures/app/config/routing.yml index 4a3e6f2..25f5ac5 100644 --- a/Tests/Fixtures/app/config/routing.yml +++ b/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 } diff --git a/Tests/Formatter/MarkdownFormatterTest.php b/Tests/Formatter/MarkdownFormatterTest.php index d058ae5..57edb02 100644 --- a/Tests/Formatter/MarkdownFormatterTest.php +++ b/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._ diff --git a/Tests/Formatter/SimpleFormatterTest.php b/Tests/Formatter/SimpleFormatterTest.php index 6868d28..9012ac8 100644 --- a/Tests/Formatter/SimpleFormatterTest.php +++ b/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',