From 2902ac3cbbc7b2fb6ac5a10e7d0a89b25f55653b Mon Sep 17 00:00:00 2001 From: Evan Villemez Date: Mon, 27 Aug 2012 12:56:19 -0400 Subject: [PATCH 1/2] working on apidoc return property --- Annotation/ApiDoc.php | 44 ++++++++++++++++++++ Extractor/ApiDocExtractor.php | 16 ++++++- Tests/Extractor/ApiDocExtratorTest.php | 2 +- Tests/Fixtures/Controller/TestController.php | 11 +++++ Tests/Fixtures/app/config/routing.yml | 6 +++ Tests/Formatter/SimpleFormatterTest.php | 13 +++++- 6 files changed, 88 insertions(+), 4 deletions(-) diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php index 1c9c9d0..8f29375 100644 --- a/Annotation/ApiDoc.php +++ b/Annotation/ApiDoc.php @@ -27,6 +27,11 @@ class ApiDoc * @var string */ private $input = null; + + /** + * @var string + */ + private $return = null; /** * @var string @@ -62,6 +67,11 @@ class ApiDoc * @var array */ private $parameters = array(); + + /** + * @var array + */ + private $response = array(); /** * @var Route @@ -88,6 +98,10 @@ class ApiDoc if (isset($data['description'])) { $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 */ @@ -181,6 +203,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 @@ -227,6 +267,10 @@ class ApiDoc if ($requirements = $this->requirements) { $data['requirements'] = $requirements; } + + if ($response = $this->response) { + $data['response'] = $response; + } return $data; } diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 6eb028f..771547a 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/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..ec52f1b 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="test_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/SimpleFormatterTest.php b/Tests/Formatter/SimpleFormatterTest.php index 6868d28..b571a0f 100644 --- a/Tests/Formatter/SimpleFormatterTest.php +++ b/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', From 504d5125f99e9f29b703fee4fba83cd78f0b354d Mon Sep 17 00:00:00 2001 From: Evan Villemez Date: Mon, 27 Aug 2012 13:25:03 -0400 Subject: [PATCH 2/2] finished up, tests passing, fixed cs --- Annotation/ApiDoc.php | 12 ++++++------ Extractor/ApiDocExtractor.php | 4 ++-- Formatter/MarkdownFormatter.php | 16 ++++++++++++++++ Parser/JmsMetadataParser.php | 5 ++--- Tests/Fixtures/Controller/TestController.php | 2 +- Tests/Formatter/MarkdownFormatterTest.php | 13 +++++++++++++ Tests/Formatter/SimpleFormatterTest.php | 7 ++++++- 7 files changed, 46 insertions(+), 13 deletions(-) diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php index 8f29375..c06eec7 100644 --- a/Annotation/ApiDoc.php +++ b/Annotation/ApiDoc.php @@ -27,7 +27,7 @@ class ApiDoc * @var string */ private $input = null; - + /** * @var string */ @@ -67,7 +67,7 @@ class ApiDoc * @var array */ private $parameters = array(); - + /** * @var array */ @@ -98,7 +98,7 @@ class ApiDoc if (isset($data['description'])) { $this->description = $data['description']; } - + if (isset($data['return'])) { $this->return = $data['return']; } @@ -203,7 +203,7 @@ class ApiDoc { $this->parameters = $parameters; } - + /** * Sets the responsed data as processed by the parsers - same format as parameters * @@ -213,7 +213,7 @@ class ApiDoc { $this->response = $response; } - + /** * @return array */ @@ -267,7 +267,7 @@ class ApiDoc if ($requirements = $this->requirements) { $data['requirements'] = $requirements; } - + if ($response = $this->response) { $data['response'] = $response; } diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 771547a..7dfee71 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -247,14 +247,14 @@ class ApiDocExtractor // 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); } 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/Fixtures/Controller/TestController.php b/Tests/Fixtures/Controller/TestController.php index ec52f1b..542b7c8 100644 --- a/Tests/Fixtures/Controller/TestController.php +++ b/Tests/Fixtures/Controller/TestController.php @@ -104,7 +104,7 @@ class TestController /** * @ApiDoc( * description="Testing return", - * return="test_type" + * return="dependency_type" * ) */ public function jmsReturnTestAction() 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 b571a0f..9012ac8 100644 --- a/Tests/Formatter/SimpleFormatterTest.php +++ b/Tests/Formatter/SimpleFormatterTest.php @@ -220,7 +220,12 @@ class SimpleFormatterTest extends WebTestCase 'uri' => '/jms-return-test', 'description' => 'Testing return', 'response' => array( - + 'a' => array( + 'dataType' => 'string', + 'required' => true, + 'description' => 'A nice description', + 'readonly' => false + ) ) ), 5 =>