From 47112613e82b3857da08756b839c07e43551d89e Mon Sep 17 00:00:00 2001 From: William DURAND Date: Thu, 15 Nov 2012 21:58:09 +0100 Subject: [PATCH 1/5] Refactor formatter, avoid code duplication --- Formatter/AbstractFormatter.php | 62 ++++++++++++++++++++++++-------- Formatter/FormatterInterface.php | 2 +- Formatter/HtmlFormatter.php | 40 ++++++--------------- Formatter/MarkdownFormatter.php | 8 ----- Formatter/SimpleFormatter.php | 25 +++++++++++-- 5 files changed, 83 insertions(+), 54 deletions(-) diff --git a/Formatter/AbstractFormatter.php b/Formatter/AbstractFormatter.php index 1ef7c3e..eadc844 100644 --- a/Formatter/AbstractFormatter.php +++ b/Formatter/AbstractFormatter.php @@ -20,7 +20,9 @@ abstract class AbstractFormatter implements FormatterInterface */ public function formatOne(ApiDoc $annotation) { - return $this->renderOne($annotation->toArray()); + return $this->renderOne( + $this->processAnnotation($annotation->toArray()) + ); } /** @@ -28,12 +30,9 @@ abstract class AbstractFormatter implements FormatterInterface */ public function format(array $collection) { - $array = array(); - foreach ($collection as $coll) { - $array[$coll['resource']][] = $coll['annotation']->toArray(); - } - - return $this->render($array); + return $this->render( + $this->processCollection($collection) + ); } /** @@ -66,15 +65,14 @@ abstract class AbstractFormatter implements FormatterInterface protected function compressNestedParameters(array $data, $parentName = null, $ignoreNestedReadOnly = false) { $newParams = array(); - foreach ($data as $name => $info) { $newName = $this->getNewName($name, $info, $parentName); $newParams[$newName] = array( - 'description' => $info['description'], - 'dataType' => $info['dataType'], - 'readonly' => $info['readonly'], - 'required' => $info['required'] + 'description' => $info['description'], + 'dataType' => $info['dataType'], + 'readonly' => $info['readonly'], + 'required' => $info['required'], ); if (isset($info['children']) && (!$info['readonly'] || !$ignoreNestedReadOnly)) { @@ -99,10 +97,46 @@ abstract class AbstractFormatter implements FormatterInterface protected function getNewName($name, $data, $parentName = null) { $newName = ($parentName) ? sprintf("%s[%s]", $parentName, $name) : $name; - - $array = (false === strpos($data['dataType'], "array of")) ? "" : "[]"; + $array = (false === strpos($data['dataType'], "array of")) ? "" : "[]"; return sprintf("%s%s", $newName, $array); } + /** + * @param array $annotation + * @return array + */ + protected function processAnnotation($annotation) + { + if (isset($annotation['parameters'])) { + $annotation['parameters'] = $this->compressNestedParameters($annotation['parameters'], null, true); + } + + if (isset($annotation['response'])) { + $annotation['response'] = $this->compressNestedParameters($annotation['response']); + } + + return $annotation; + } + + /** + * @param array[ApiDoc] $collection + * @return array + */ + protected function processCollection(array $collection) + { + $array = array(); + foreach ($collection as $coll) { + $array[$coll['resource']][] = $coll['annotation']->toArray(); + } + + $processedCollection = array(); + foreach ($array as $path => $annotations) { + foreach ($annotations as $annotation) { + $processedCollection[$path][] = $this->processAnnotation($annotation); + } + } + + return $processedCollection; + } } diff --git a/Formatter/FormatterInterface.php b/Formatter/FormatterInterface.php index 1a3302f..95147c2 100644 --- a/Formatter/FormatterInterface.php +++ b/Formatter/FormatterInterface.php @@ -18,7 +18,7 @@ interface FormatterInterface /** * Format a collection of documentation data. * - * @param array $collection + * @param array[ApiDoc] $collection * @return string|array */ public function format(array $collection); diff --git a/Formatter/HtmlFormatter.php b/Formatter/HtmlFormatter.php index 2981ca1..54677c0 100644 --- a/Formatter/HtmlFormatter.php +++ b/Formatter/HtmlFormatter.php @@ -36,7 +36,7 @@ class HtmlFormatter extends AbstractFormatter private $enableSandbox; /** - * @var \Symfony\Component\Templating\EngineInterface + * @var EngineInterface */ private $engine; @@ -98,6 +98,9 @@ class HtmlFormatter extends AbstractFormatter $this->requestFormatMethod = $method; } + /** + * @param string $format + */ public function setDefaultRequestFormat($format) { $this->defaultRequestFormat = $format; @@ -108,16 +111,11 @@ class HtmlFormatter extends AbstractFormatter */ protected function renderOne(array $data) { - if (isset($data['parameters'])) { - $data['parameters'] = $this->compressNestedParameters($data['parameters'], null, true); - } - - if (isset($data['response'])) { - $data['response'] = $this->compressNestedParameters($data['response']); - } - return $this->engine->render('NelmioApiDocBundle::resource.html.twig', array_merge( - array('data' => $data, 'displayContent' => true), + array( + 'data' => $data, + 'displayContent' => true, + ), $this->getGlobalVars() )); } @@ -127,25 +125,10 @@ class HtmlFormatter extends AbstractFormatter */ protected function render(array $collection) { - $processedCollection = array(); - - foreach ($collection as $path => $methods) { - $processedCollection[$path] = array(); - foreach ($methods as $method) { - if (isset($method['parameters'])) { - $method['parameters'] = $this->compressNestedParameters($method['parameters'], null, true); - } - - if (isset($method['response'])) { - $method['response'] = $this->compressNestedParameters($method['response']); - } - - $processedCollection[$path][] = $method; - } - } - return $this->engine->render('NelmioApiDocBundle::resources.html.twig', array_merge( - array('resources' => $processedCollection), + array( + 'resources' => $collection, + ), $this->getGlobalVars() )); } @@ -167,5 +150,4 @@ class HtmlFormatter extends AbstractFormatter 'js' => file_get_contents(__DIR__ . '/../Resources/public/js/all.js'), ); } - } diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php index b794ba4..3f3ac32 100644 --- a/Formatter/MarkdownFormatter.php +++ b/Formatter/MarkdownFormatter.php @@ -18,14 +18,6 @@ class MarkdownFormatter extends AbstractFormatter */ protected function renderOne(array $data) { - if (isset($data['parameters'])) { - $data['parameters'] = $this->compressNestedParameters($data['parameters'], null, true); - } - - if (isset($data['response'])) { - $data['response'] = $this->compressNestedParameters($data['response']); - } - $markdown = sprintf("### `%s` %s ###\n", $data['method'], $data['uri']); if (isset($data['description'])) { diff --git a/Formatter/SimpleFormatter.php b/Formatter/SimpleFormatter.php index 788f913..e6aab92 100644 --- a/Formatter/SimpleFormatter.php +++ b/Formatter/SimpleFormatter.php @@ -11,14 +11,36 @@ namespace Nelmio\ApiDocBundle\Formatter; +use Nelmio\ApiDocBundle\Annotation\ApiDoc; + class SimpleFormatter extends AbstractFormatter { + /** + * {@inheritdoc} + */ + public function formatOne(ApiDoc $annotation) + { + return $annotation->toArray(); + } + + /** + * {@inheritdoc} + */ + public function format(array $collection) + { + $array = array(); + foreach ($collection as $coll) { + $array[$coll['resource']][] = $coll['annotation']->toArray(); + } + + return $array; + } + /** * {@inheritdoc} */ protected function renderOne(array $data) { - return $data; } /** @@ -26,6 +48,5 @@ class SimpleFormatter extends AbstractFormatter */ protected function render(array $collection) { - return $collection; } } From 84c82f3b940ef2c054f1938ec6becea624ecc649 Mon Sep 17 00:00:00 2001 From: William DURAND Date: Sat, 17 Nov 2012 17:38:35 +0100 Subject: [PATCH 2/5] Allow HtmlFormatter to be overrided --- Formatter/HtmlFormatter.php | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Formatter/HtmlFormatter.php b/Formatter/HtmlFormatter.php index 54677c0..8204891 100644 --- a/Formatter/HtmlFormatter.php +++ b/Formatter/HtmlFormatter.php @@ -16,39 +16,39 @@ use Symfony\Component\Templating\EngineInterface; class HtmlFormatter extends AbstractFormatter { /** - * @var array + * @var string */ - private $authentication; + protected $apiName; /** * @var string */ - private $apiName; + protected $endpoint; /** * @var string */ - private $endpoint; + protected $defaultRequestFormat; + + /** + * @var EngineInterface + */ + protected $engine; /** * @var boolean */ private $enableSandbox; - /** - * @var EngineInterface - */ - private $engine; - /** * @var string */ private $requestFormatMethod; /** - * @var string + * @var array */ - private $defaultRequestFormat; + private $authentication; /** * @param array $authentication From 2f62db82a94b19178689415244fcbfacbb874e53 Mon Sep 17 00:00:00 2001 From: William DURAND Date: Sat, 17 Nov 2012 17:39:54 +0100 Subject: [PATCH 3/5] 'type' becomes 'dataType' for consistency purpose --- Extractor/ApiDocExtractor.php | 8 ++++---- Resources/views/method.html.twig | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index f0306f6..71fcd9d 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -285,7 +285,7 @@ class ApiDocExtractor if ('_method' !== $name) { $requirements[$name] = array( 'requirement' => $value, - 'type' => '', + 'dataType' => '', 'description' => '', ); } @@ -303,7 +303,7 @@ class ApiDocExtractor $found = false; foreach ($paramDocs as $paramDoc) { if (preg_match(sprintf($regexp, preg_quote($var)), $paramDoc, $matches)) { - $requirements[$var]['type'] = isset($matches[1]) ? $matches[1] : ''; + $requirements[$var]['dataType'] = isset($matches[1]) ? $matches[1] : ''; $requirements[$var]['description'] = $matches[2]; if (!isset($requirements[$var]['requirement'])) { @@ -316,7 +316,7 @@ class ApiDocExtractor } if (!isset($requirements[$var]) && false === $found) { - $requirements[$var] = array('requirement' => '', 'type' => '', 'description' => ''); + $requirements[$var] = array('requirement' => '', 'dataType' => '', 'description' => ''); } } @@ -344,7 +344,7 @@ class ApiDocExtractor if ($annot->strict) { $annotation->addRequirement($annot->name, array( 'requirement' => $annot->requirements, - 'type' => '', + 'dataType' => '', 'description' => $annot->description, )); } else { diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig index ae9f4f1..097841b 100644 --- a/Resources/views/method.html.twig +++ b/Resources/views/method.html.twig @@ -46,7 +46,7 @@ {{ name }} {{ infos.requirement }} - {{ infos.type }} + {{ infos.dataType }} {{ infos.description }} {% endfor %} From 1d721838569310531ae90c8dc3ea7980e225fe70 Mon Sep 17 00:00:00 2001 From: William DURAND Date: Sat, 17 Nov 2012 17:53:45 +0100 Subject: [PATCH 4/5] Fix CS --- Extractor/ApiDocExtractor.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 71fcd9d..af31b50 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -353,7 +353,7 @@ class ApiDocExtractor 'description' => $annot->description, )); } - } else if (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { + } elseif (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { $annotation->addParameter($annot->name, array( 'required' => !$annot->nullable, 'dataType' => $annot->requirements, From b31d439dac3c01b0b28332e439c07d4fe5a578cc Mon Sep 17 00:00:00 2001 From: William DURAND Date: Sat, 17 Nov 2012 18:05:05 +0100 Subject: [PATCH 5/5] Fix tests --- Formatter/MarkdownFormatter.php | 4 ++-- Tests/Formatter/SimpleFormatterTest.php | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php index 3f3ac32..8e3dd76 100644 --- a/Formatter/MarkdownFormatter.php +++ b/Formatter/MarkdownFormatter.php @@ -43,8 +43,8 @@ class MarkdownFormatter extends AbstractFormatter $markdown .= sprintf(" - Requirement: %s\n", $infos['requirement']); } - if (!empty($infos['type'])) { - $markdown .= sprintf(" - Type: %s\n", $infos['type']); + if (!empty($infos['dataType'])) { + $markdown .= sprintf(" - Type: %s\n", $infos['dataType']); } if (!empty($infos['description'])) { diff --git a/Tests/Formatter/SimpleFormatterTest.php b/Tests/Formatter/SimpleFormatterTest.php index 0fef777..af5236b 100644 --- a/Tests/Formatter/SimpleFormatterTest.php +++ b/Tests/Formatter/SimpleFormatterTest.php @@ -48,7 +48,7 @@ class SimpleFormatterTest extends WebTestCase ), 'description' => 'index action', 'requirements' => array( - '_format' => array('type' => '', 'description' => '', 'requirement' => ''), + '_format' => array('dataType' => '', 'description' => '', 'requirement' => ''), ), ), 1 => @@ -73,7 +73,7 @@ class SimpleFormatterTest extends WebTestCase ), 'description' => 'index action', 'requirements' => array( - '_format' => array('type' => '', 'description' => '', 'requirement' => ''), + '_format' => array('dataType' => '', 'description' => '', 'requirement' => ''), ), ), 2 => @@ -106,7 +106,7 @@ class SimpleFormatterTest extends WebTestCase ), 'description' => 'create test', 'requirements' => array( - '_format' => array('type' => '', 'description' => '', 'requirement' => ''), + '_format' => array('dataType' => '', 'description' => '', 'requirement' => ''), ), ), 3 => @@ -139,7 +139,7 @@ class SimpleFormatterTest extends WebTestCase ), 'description' => 'create test', 'requirements' => array( - '_format' => array('type' => '', 'description' => '', 'requirement' => ''), + '_format' => array('dataType' => '', 'description' => '', 'requirement' => ''), ), ), ), @@ -173,7 +173,7 @@ class SimpleFormatterTest extends WebTestCase 'uri' => '/any/{foo}', 'requirements' => array( - 'foo' => array('type' => '', 'description' => '', 'requirement' => ''), + 'foo' => array('dataType' => '', 'description' => '', 'requirement' => ''), ), 'description' => 'Action without HTTP verb', ), @@ -290,8 +290,8 @@ With multiple lines.', 'uri' => '/my-commented/{id}/{page}', 'requirements' => array( - 'id' => array('type' => 'int', 'description' => 'A nice comment', 'requirement' => ''), - 'page' => array('type' => 'int', 'description' => '', 'requirement' => ''), + 'id' => array('dataType' => 'int', 'description' => 'A nice comment', 'requirement' => ''), + 'page' => array('dataType' => 'int', 'description' => '', 'requirement' => ''), ), '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." @@ -302,7 +302,7 @@ With multiple lines.', 'uri' => '/yet-another/{id}', 'requirements' => array( - 'id' => array('type' => '', 'description' => '', 'requirement' => '\d+') + 'id' => array('dataType' => '', 'description' => '', 'requirement' => '\d+') ), ), 7 => @@ -354,7 +354,7 @@ With multiple lines.', ), 'description' => 'index action', 'requirements' => array( - '_format' => array('type' => '', 'description' => '', 'requirement' => ''), + '_format' => array('dataType' => '', 'description' => '', 'requirement' => ''), ), );