RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-02-02 15:51:48 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #218 from konradpodgorski/feature/extendedAnnotation

Browse Source 
Option to set requirements and parameters directly from ApiDoc annotation
This commit is contained in:
William Durand 2013-10-15 15:39:44 -07:00
commit bef7da0ef9
5 changed files with 129 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Annotation/ApiDoc.php
View File

@ -153,6 +153,39 @@ class ApiDoc
}
}
if (isset($data['requirements'])) {
foreach ($data['requirements'] as $requirement) {
if (!isset($requirement['name'])) {
throw new \InvalidArgumentException('A "requirement" element has to contain a "name" attribute');
}
$name = $requirement['name'];
unset($requirement['name']);
$this->addRequirement($name, $requirement);
}
}
if (isset($data['parameters'])) {
foreach ($data['parameters'] as $parameter) {
if (!isset($parameter['name'])) {
throw new \InvalidArgumentException('A "parameter" element has to contain a "name" attribute');
}
if (!isset($parameter['dataType'])) {
throw new \InvalidArgumentException(sprintf(
'"%s" parameter element has to contain a "dataType" attribute',
$parameter['name']
));
}
$name = $parameter['name'];
unset($parameter['name']);
$this->addParameter($name, $parameter);
}
}
if (isset($data['output'])) {
$this->output = $data['output'];
}

24
README.md
View File

@ -89,6 +89,26 @@ class YourController extends Controller
public function postAction()
{
}
/**
* @ApiDoc(
* description="Returns a collection of Object",
* requirements={
* {
* "name"="limit",
* "dataType"="integer",
* "requirement"="\d+",
* "description"="how many objects to return"
* }
* },
* parameters={
* {"name"="categoryId", "dataType"="integer", "required"=true, "description"="category id"}
* }
* )
*/
public function cgetAction($id)
{
}
}
```
@ -104,6 +124,10 @@ The following properties are available:
* `filters`: an array of filters;
* `requirements`: an array of requirements;
* `parameters`: an array of parameters;
* `input`: the input type associated to the method (currently this supports Form Types, classes with JMS Serializer
metadata, and classes with Validation component metadata) useful for POST|PUT methods, either as FQCN or as form type
(if it is registered in the form factory in the container).

4
Resources/views/method.html.twig
View File

@ -123,10 +123,10 @@
{% if not infos.readonly %}
<tr>
<td>{{ name }}</td>
<td>{{ infos.dataType }}</td>
<td>{{ infos.dataType is defined ? infos.dataType : '' }}</td>
<td>{{ infos.required ? 'true' : 'false' }}</td>
<td>{{ infos.format }}</td>
<td>{{ infos.description }}</td>
<td>{{ infos.description is defined ? infos.description : '' }}</td>
</tr>
{% endif %}
{% endfor %}

55
Tests/Annotation/ApiDocTest.php
View File

@ -28,6 +28,8 @@ class ApiDocTest extends TestCase
$this->assertFalse($annot->isResource());
$this->assertFalse($annot->getDeprecated());
$this->assertFalse(isset($array['description']));
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertNull($annot->getInput());
$this->assertFalse($array['authentication']);
}
@ -47,6 +49,8 @@ class ApiDocTest extends TestCase
$this->assertFalse($annot->isResource());
$this->assertFalse($annot->getDeprecated());
$this->assertFalse(isset($array['description']));
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertNull($annot->getInput());
}
@ -64,6 +68,8 @@ class ApiDocTest extends TestCase
$this->assertFalse($annot->isResource());
$this->assertFalse($annot->getDeprecated());
$this->assertEquals($data['description'], $array['description']);
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertNull($annot->getInput());
}
@ -82,6 +88,8 @@ class ApiDocTest extends TestCase
$this->assertFalse($annot->isResource());
$this->assertFalse($annot->getDeprecated());
$this->assertEquals($data['description'], $array['description']);
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertEquals($data['input'], $annot->getInput());
}
@ -102,6 +110,8 @@ class ApiDocTest extends TestCase
$this->assertTrue($annot->isResource());
$this->assertTrue($annot->getDeprecated());
$this->assertEquals($data['description'], $array['description']);
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertEquals($data['input'], $annot->getInput());
}
@ -121,6 +131,8 @@ class ApiDocTest extends TestCase
$this->assertFalse(isset($array['filters']));
$this->assertFalse($annot->isResource());
$this->assertEquals($data['description'], $array['description']);
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertEquals($data['deprecated'], $array['deprecated']);
$this->assertEquals($data['input'], $annot->getInput());
}
@ -145,6 +157,8 @@ class ApiDocTest extends TestCase
$this->assertEquals(array('a-filter' => array()), $array['filters']);
$this->assertTrue($annot->isResource());
$this->assertEquals($data['description'], $array['description']);
$this->assertFalse(isset($array['requirements']));
$this->assertFalse(isset($array['parameters']));
$this->assertEquals($data['deprecated'], $array['deprecated']);
$this->assertNull($annot->getInput());
}
@ -232,4 +246,45 @@ class ApiDocTest extends TestCase
$this->assertEquals($data['cache'], $array['cache']);
}
public function testConstructWithRequirements()
{
$data = array(
'requirements' => array(
array(
'name' => 'fooId',
'requirement' => '\d+',
'dataType' => 'integer',
'description' => 'This requirement might be used withing action method directly from Request object'
)
)
);
$annot = new ApiDoc($data);
$array = $annot->toArray();
$this->assertTrue(is_array($array));
$this->assertTrue(isset($array['requirements']['fooId']));
$this->assertTrue(isset($array['requirements']['fooId']['dataType']));
}
public function testConstructWithParameters()
{
$data = array(
'parameters' => array(
array(
'name' => 'fooId',
'dataType' => 'integer',
'description' => 'Some description'
)
)
);
$annot = new ApiDoc($data);
$array = $annot->toArray();
$this->assertTrue(is_array($array));
$this->assertTrue(isset($array['parameters']['fooId']));
$this->assertTrue(isset($array['parameters']['fooId']['dataType']));
}
}

15
Tests/Fixtures/Controller/TestController.php
View File

@ -198,4 +198,19 @@ class TestController
public function jmsReturnNestedOutputAction()
{
}
/**
* @ApiDoc(
* description="Returns a collection of Object",
* requirements={
* {"name"="limit", "dataType"="integer", "requirement"="\d+", "description"="how many objects to return"}
* },
* parameters={
* {"name"="categoryId", "dataType"="integer", "required"=true, "description"="category id"}
* }
* )
*/
public function cgetAction($id)
{
}
}