diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php index 28a8f24..e678411 100644 --- a/Annotation/ApiDoc.php +++ b/Annotation/ApiDoc.php @@ -110,6 +110,11 @@ class ApiDoc */ private $cache; + /** + * @var boolean + */ + private $deprecated = false; + /** * @var array */ @@ -159,6 +164,10 @@ class ApiDoc if (isset($data['section'])) { $this->section = $data['section']; } + + if (isset($data['deprecated'])) { + $this->deprecated = $data['deprecated']; + } } /** @@ -330,7 +339,7 @@ class ApiDoc } /** - * @param boolean $secured + * @param boolean $authentication */ public function setAuthentication($authentication) { @@ -353,6 +362,23 @@ class ApiDoc $this->cache = (int) $cache; } + /** + * @return boolean + */ + public function getDeprecated() + { + return $this->deprecated; + } + + /** + * @param boolean $deprecated + */ + public function setDeprecated($deprecated) + { + $this->deprecated = (bool) $deprecated; + return $this; + } + /** * @return array */ @@ -401,6 +427,7 @@ class ApiDoc $data['https'] = $this->https; $data['authentication'] = $this->authentication; + $data['deprecated'] = $this->deprecated; return $data; } diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 3568ca5..e338fe9 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -70,7 +70,7 @@ class ApiDocExtractor * You can extend this method if you don't want all the routes * to be included. * - * @return \Traversable Iterator for a RouteCollection + * @return Route[] An array of routes */ public function getRoutes() { @@ -94,13 +94,11 @@ class ApiDocExtractor * * @param array $routes array of Route-objects for which the annotations should be extracted * - * @throws \InvalidArgumentException if one element of the input isnt an instance of Route - * * @return array */ public function extractAnnotations(array $routes) { - $array = array(); + $array = array(); $resources = array(); foreach ($routes as $route) { @@ -384,7 +382,7 @@ class ApiDocExtractor )); } elseif (is_a($annot, self::JMS_SECURITY_EXTRA_SECURE_CLASS)) { $annotation->setAuthentication(true); - } elseif (is_a($annot, self::CACHE_ANNOTATION_CLASS)) { + } elseif (is_a($annot, self::CACHE_ANNOTATION_CLASS)) { $annotation->setCache($annot->getMaxAge()); } } diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php index f869ea0..e579d06 100644 --- a/Formatter/MarkdownFormatter.php +++ b/Formatter/MarkdownFormatter.php @@ -20,6 +20,11 @@ class MarkdownFormatter extends AbstractFormatter { $markdown = sprintf("### `%s` %s ###\n", $data['method'], $data['uri']); + if(isset($data['deprecated'])) { + $markdown .= "### This method is deprecated ###"; + $markdown .= "\n\n"; + } + if (isset($data['description'])) { $markdown .= sprintf("\n_%s_", $data['description']); } diff --git a/README.md b/README.md index 898a74e..1e31c15 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,8 @@ The following properties are available: * `description`: a description of the API method; +* `deprecated`: allow to set method as deprecated (default: `false`); + * `filters`: an array of filters; * `input`: the input type associated to the method, currently this supports Form Types, and classes with JMS Serializer diff --git a/Resources/public/css/screen.css b/Resources/public/css/screen.css index a41eb11..1c0c6b9 100644 --- a/Resources/public/css/screen.css +++ b/Resources/public/css/screen.css @@ -258,7 +258,7 @@ li.operation div.heading h3 span { margin: 0; padding: 0; } -li.operation div.heading h3 span.http_method a { +li.operation div.heading h3 span.http_method a, li.operation div.heading h3 span.deprecated a { text-transform: uppercase; text-decoration: none; color: white; @@ -272,6 +272,10 @@ li.operation div.heading h3 span.http_method a { border-radius: 2px; background-color: #ccc; } +li.operation div.heading h3 span.deprecated a { + width: 75px; + background-color: #F00; +} li.operation div.heading h3 span.path { padding-left: 10px; } diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig index f6fdba5..99e1369 100644 --- a/Resources/views/method.html.twig +++ b/Resources/views/method.html.twig @@ -1,10 +1,16 @@
  • -
    +

    {{ data.method|upper }} + {% if data.deprecated %} + + DEPRECATED + + {% endif %} + {% if data.https %} HTTPS {% endif %} diff --git a/Tests/Annotation/ApiDocTest.php b/Tests/Annotation/ApiDocTest.php index 6a7750a..3c7eb5f 100644 --- a/Tests/Annotation/ApiDocTest.php +++ b/Tests/Annotation/ApiDocTest.php @@ -26,6 +26,7 @@ class ApiDocTest extends TestCase $this->assertTrue(is_array($array)); $this->assertFalse(isset($array['filters'])); $this->assertFalse($annot->isResource()); + $this->assertFalse($annot->getDeprecated()); $this->assertFalse(isset($array['description'])); $this->assertNull($annot->getInput()); $this->assertFalse($array['authentication']); @@ -44,6 +45,7 @@ class ApiDocTest extends TestCase $this->assertTrue(is_array($array)); $this->assertFalse(isset($array['filters'])); $this->assertFalse($annot->isResource()); + $this->assertFalse($annot->getDeprecated()); $this->assertFalse(isset($array['description'])); $this->assertNull($annot->getInput()); } @@ -60,6 +62,7 @@ class ApiDocTest extends TestCase $this->assertTrue(is_array($array)); $this->assertFalse(isset($array['filters'])); $this->assertFalse($annot->isResource()); + $this->assertFalse($annot->getDeprecated()); $this->assertEquals($data['description'], $array['description']); $this->assertNull($annot->getInput()); } @@ -77,6 +80,7 @@ class ApiDocTest extends TestCase $this->assertTrue(is_array($array)); $this->assertFalse(isset($array['filters'])); $this->assertFalse($annot->isResource()); + $this->assertFalse($annot->getDeprecated()); $this->assertEquals($data['description'], $array['description']); $this->assertEquals($data['input'], $annot->getInput()); } @@ -86,6 +90,7 @@ class ApiDocTest extends TestCase $data = array( 'resource' => true, 'description' => 'Heya', + 'deprecated' => true, 'input' => 'My\Form\Type', ); @@ -95,6 +100,7 @@ class ApiDocTest extends TestCase $this->assertTrue(is_array($array)); $this->assertFalse(isset($array['filters'])); $this->assertTrue($annot->isResource()); + $this->assertTrue($annot->getDeprecated()); $this->assertEquals($data['description'], $array['description']); $this->assertEquals($data['input'], $annot->getInput()); } @@ -104,6 +110,7 @@ class ApiDocTest extends TestCase $data = array( 'resource' => false, 'description' => 'Heya', + 'deprecated' => false, 'input' => 'My\Form\Type', ); @@ -114,6 +121,7 @@ class ApiDocTest extends TestCase $this->assertFalse(isset($array['filters'])); $this->assertFalse($annot->isResource()); $this->assertEquals($data['description'], $array['description']); + $this->assertEquals($data['deprecated'], $array['deprecated']); $this->assertEquals($data['input'], $annot->getInput()); } @@ -121,6 +129,7 @@ class ApiDocTest extends TestCase { $data = array( 'resource' => true, + 'deprecated' => false, 'description' => 'Heya', 'filters' => array( array('name' => 'a-filter'), @@ -136,6 +145,7 @@ class ApiDocTest extends TestCase $this->assertEquals(array('a-filter' => array()), $array['filters']); $this->assertTrue($annot->isResource()); $this->assertEquals($data['description'], $array['description']); + $this->assertEquals($data['deprecated'], $array['deprecated']); $this->assertNull($annot->getInput()); } diff --git a/Tests/Formatter/MarkdownFormatterTest.php b/Tests/Formatter/MarkdownFormatterTest.php index 9572048..d51d4f7 100644 --- a/Tests/Formatter/MarkdownFormatterTest.php +++ b/Tests/Formatter/MarkdownFormatterTest.php @@ -29,6 +29,8 @@ class MarkdownFormatterTest extends WebTestCase ## /tests ## ### `GET` /tests.{_format} ### +### This method is deprecated ### + _index action_ @@ -50,6 +52,8 @@ b: ### `GET` /tests.{_format} ### +### This method is deprecated ### + _index action_ @@ -71,6 +75,8 @@ b: ### `POST` /tests.{_format} ### +### This method is deprecated ### + _create test_ @@ -99,6 +105,8 @@ c: ### `POST` /tests.{_format} ### +### This method is deprecated ### + _create test_ @@ -129,6 +137,8 @@ c: ## /tests2 ## ### `POST` /tests2.{_format} ### +### This method is deprecated ### + _post test 2_ @@ -139,6 +149,8 @@ _post test 2_ ### `POST` /another-post ### +### This method is deprecated ### + _create another test_ @@ -152,11 +164,15 @@ a: ### `ANY` /any ### +### This method is deprecated ### + _Action without HTTP verb_ ### `ANY` /any/{foo} ### +### This method is deprecated ### + _Action without HTTP verb_ @@ -167,10 +183,14 @@ _Action without HTTP verb_ ### `ANY` /authenticated ### +### This method is deprecated ### + ### `POST` /jms-input-test ### +### This method is deprecated ### + _Testing JMS_ @@ -264,6 +284,8 @@ nested_array[]: ### `GET` /jms-return-test ### +### This method is deprecated ### + _Testing return_ @@ -276,6 +298,8 @@ a: ### `ANY` /my-commented/{id}/{page} ### +### This method is deprecated ### + _This method is useful to test if the getDocComment works._ @@ -291,6 +315,8 @@ _This method is useful to test if the getDocComment works._ ### `ANY` /secure-route ### +### This method is deprecated ### + #### Requirements #### @@ -301,6 +327,8 @@ _This method is useful to test if the getDocComment works._ ### `ANY` /yet-another/{id} ### +### This method is deprecated ### + #### Requirements #### @@ -311,6 +339,8 @@ _This method is useful to test if the getDocComment works._ ### `GET` /z-action-with-query-param ### +### This method is deprecated ### + #### Filters #### @@ -322,6 +352,8 @@ page: ### `POST` /z-action-with-request-param ### +### This method is deprecated ### + #### Parameters #### @@ -346,6 +378,8 @@ MARKDOWN; $expected = << false, 'authentication' => false, + 'deprecated' => false, ), 1 => array ( @@ -93,6 +94,7 @@ class SimpleFormatterTest extends WebTestCase ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 2 => array ( @@ -134,6 +136,7 @@ class SimpleFormatterTest extends WebTestCase ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 3 => array ( @@ -175,6 +178,7 @@ class SimpleFormatterTest extends WebTestCase ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), ), 'others' => @@ -196,6 +200,7 @@ class SimpleFormatterTest extends WebTestCase ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 1 => array ( @@ -204,6 +209,7 @@ class SimpleFormatterTest extends WebTestCase 'description' => 'Action without HTTP verb', 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 2 => array ( @@ -221,6 +227,7 @@ class SimpleFormatterTest extends WebTestCase ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 3 => array ( @@ -228,6 +235,7 @@ class SimpleFormatterTest extends WebTestCase 'uri' => '/authenticated', 'https' => false, 'authentication' => true, + 'deprecated' => false, ), 4 => array( @@ -366,6 +374,7 @@ With multiple lines.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 5 => array( @@ -384,6 +393,7 @@ With multiple lines.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 6 => array( @@ -411,6 +421,7 @@ And, it supports multilines until the first \'@\' char.', '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.", 'authentication' => false, + 'deprecated' => false, ), 7 => array( @@ -427,6 +438,7 @@ And, it supports multilines until the first \'@\' char.', ), 'https' => true, 'authentication' => false, + 'deprecated' => false, ), 8 => array( @@ -443,6 +455,7 @@ And, it supports multilines until the first \'@\' char.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 9 => array( @@ -458,6 +471,7 @@ And, it supports multilines until the first \'@\' char.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), 10 => array( @@ -475,6 +489,7 @@ And, it supports multilines until the first \'@\' char.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ), ), '/tests2' => @@ -495,6 +510,28 @@ And, it supports multilines until the first \'@\' char.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, + ), + ), + '/tests2' => + array ( + 0 => + array ( + 'method' => 'POST', + 'uri' => '/tests2.{_format}', + 'description' => 'post test 2', + 'requirements' => + array ( + '_format' => + array ( + 'requirement' => '', + 'dataType' => '', + 'description' => '', + ), + ), + 'https' => false, + 'authentication' => false, + 'deprecated' => false, ), ), ); @@ -531,6 +568,7 @@ And, it supports multilines until the first \'@\' char.', ), 'https' => false, 'authentication' => false, + 'deprecated' => false, ); $this->assertEquals($expected, $result);