mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-02 07:41:43 +03:00
Ability to mark function as deprecated
This commit is contained in:
Patryk Kala
William DURAND
parent
d6491e77bc
commit
3b6e9da91a
@ -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;
|
||||
}
|
||||
|
||||
@ -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());
|
||||
}
|
||||
}
|
||||
|
||||
@ -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']);
|
||||
}
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
@ -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 %}
|
||||
|
||||
@ -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());
|
||||
}
|
||||
|
||||
|
||||
@ -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_
|
||||
|
||||
|
||||
@ -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);
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user