Ability to mark function as deprecated

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;
     }

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,8 +94,6 @@ 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)

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']);
         }

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

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;
 }

Resources/views/method.html.twig

@@ -1,10 +1,16 @@
 <li class="{{ data.method|lower }} operation">
-    <div class="heading toggler">
+    <div class="heading toggler{% if data.deprecated %} deprecated{% endif %}">
     <h3>
         <span class="http_method">
             <a>{{ data.method|upper }}</a>
         </span>
 
+        {% if data.deprecated %}
+        <span class="deprecated">
+            <a>DEPRECATED</a>
+        </span>
+        {% endif %}
+
         {% if data.https %}
             <img src="{{ asset('bundles/nelmioapidoc/image/lock.png') }}" class="icon" alt="HTTPS" />
         {% endif %}

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());
     }
 

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 = <<<MARKDOWN
 ### `GET` /tests.{_format} ###
+### This method is deprecated ###
+
 
 _index action_
 

Tests/Formatter/SimpleFormatterTest.php

@@ -60,6 +60,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => 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);