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 #70 from evillemez/apidoc_return

Browse Source 
Implemented @ApiDoc `return` property
This commit is contained in:
William Durand 2012-08-27 23:41:42 -07:00
commit cbdddfebb5
9 changed files with 124 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
Annotation/ApiDoc.php
View File

@ -28,6 +28,11 @@ class ApiDoc
*/
private $input = null;
/**
* @var string
*/
private $return = null;
/**
* @var string
*/
@ -63,6 +68,11 @@ class ApiDoc
*/
private $parameters = array();
/**
* @var array
*/
private $response = array();
/**
* @var Route
*/
@ -89,6 +99,10 @@ class ApiDoc
$this->description = $data['description'];
}
if (isset($data['return'])) {
$this->return = $data['return'];
}
$this->isResource = isset($data['resource']) && $data['resource'];
}
@ -126,6 +140,14 @@ class ApiDoc
return $this->input;
}
/**
* @return string|null
*/
public function getReturn()
{
return $this->return;
}
/**
* @return string
*/
@ -182,6 +204,24 @@ class ApiDoc
$this->parameters = $parameters;
}
/**
* Sets the responsed data as processed by the parsers - same format as parameters
*
* @param array $response
*/
public function setResponse(array $response)
{
$this->response = $response;
}
/**
* @return array
*/
public function getResponse()
{
return $this->response;
}
/**
* @param Route $route
*/
@ -228,6 +268,10 @@ class ApiDoc
$data['requirements'] = $requirements;
}
if ($response = $this->response) {
$data['response'] = $response;
}
return $data;
}
}

16
Extractor/ApiDocExtractor.php
View File

@ -223,7 +223,7 @@ class ApiDocExtractor
// doc
$annotation->setDocumentation($this->getDocCommentText($method));
// input
// input (populates 'parameters' for the formatters)
if (null !== $input = $annotation->getInput()) {
$parameters = array();
@ -244,6 +244,20 @@ class ApiDocExtractor
$annotation->setParameters($parameters);
}
// return (populates 'response' for the formatters)
if (null !== $return = $annotation->getReturn()) {
$response = array();
foreach ($this->parsers as $parser) {
if ($parser->supports($return)) {
$response = $parser->parse($return);
break;
}
}
$annotation->setResponse($response);
}
// requirements
$requirements = array();
foreach ($route->getRequirements() as $name => $value) {

16
Formatter/MarkdownFormatter.php
View File

@ -85,6 +85,22 @@ class MarkdownFormatter extends AbstractFormatter
}
}
if (isset($data['response'])) {
$markdown .= "#### Response ####\n\n";
foreach ($data['response'] as $name => $parameter) {
$markdown .= sprintf("%s:\n\n", $name);
$markdown .= sprintf(" * type: %s\n", $parameter['dataType']);
$markdown .= sprintf(" * required: %s\n", $parameter['required'] ? 'true' : 'false');
if (isset($parameter['description']) && !empty($parameter['description'])) {
$markdown .= sprintf(" * description: %s\n", $parameter['description']);
}
$markdown .= "\n";
}
}
return $markdown;
}

1
Parser/JmsMetadataParser.php
View File

@ -81,7 +81,6 @@ class JmsMetadataParser implements ParserInterface
//TODO: regex comment to get description - or move doc comment parsing functionality from `ApiDocExtractor` to a new location
//in order to reuse it here
return $description;
}

2
Tests/Extractor/ApiDocExtratorTest.php
View File

@ -22,7 +22,7 @@ class ApiDocExtractorTest extends WebTestCase
$data = $extractor->all();
$this->assertTrue(is_array($data));
$this->assertCount(11, $data);
$this->assertCount(12, $data);
foreach ($data as $d) {
$this->assertTrue(is_array($d));

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

@ -100,4 +100,15 @@ class TestController
public function jmsInputTestAction()
{
}
/**
* @ApiDoc(
* description="Testing return",
* return="dependency_type"
* )
*/
public function jmsReturnTestAction()
{
}
}

6
Tests/Fixtures/app/config/routing.yml
View File

@ -46,6 +46,12 @@ test_route_9:
requirements:
_method: POST
test_route_10:
pattern: /jms-return-test
defaults: { _controller: NelmioApiDocTestBundle:Test:jmsReturnTest }
requirements:
_method: GET
test_service_route_1:
pattern: /tests.{_format}
defaults: { _controller: nemlio.test.controller:indexAction, _format: json }

13
Tests/Formatter/MarkdownFormatterTest.php
View File

@ -186,6 +186,19 @@ arr:
* description: No description.
### `GET` /jms-return-test ###
_Testing return_
#### Response ####
a:
* type: string
* required: true
* description: A nice description
### `ANY` /my-commented/{id}/{page} ###
_This method is useful to test if the getDocComment works._

18
Tests/Formatter/SimpleFormatterTest.php
View File

@ -215,6 +215,20 @@ class SimpleFormatterTest extends WebTestCase
'description' => 'Testing JMS'
),
4 =>
array(
'method' => 'GET',
'uri' => '/jms-return-test',
'description' => 'Testing return',
'response' => array(
'a' => array(
'dataType' => 'string',
'required' => true,
'description' => 'A nice description',
'readonly' => false
)
)
),
5 =>
array(
'method' => 'ANY',
'uri' => '/my-commented/{id}/{page}',
@ -226,7 +240,7 @@ class SimpleFormatterTest extends WebTestCase
'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."
),
5 =>
6 =>
array(
'method' => 'ANY',
'uri' => '/yet-another/{id}',
@ -235,7 +249,7 @@ class SimpleFormatterTest extends WebTestCase
'id' => array('type' => '', 'description' => '', 'requirement' => '\d+')
),
),
6 =>
7 =>
array(
'method' => 'GET',
'uri' => '/z-action-with-query-param',