Permalink
Browse files

Merge pull request #70 from evillemez/apidoc_return

Implemented @ApiDoc `return` property
  • Loading branch information...
2 parents b085338 + 504d512 commit cbdddfebb539dca86db999dd8b6f64961321dfb8 @willdurand willdurand committed Aug 28, 2012
View
@@ -31,6 +31,11 @@ class ApiDoc
/**
* @var string
*/
+ private $return = null;
+
+ /**
+ * @var string
+ */
private $description = null;
/**
@@ -64,6 +69,11 @@ class ApiDoc
private $parameters = array();
/**
+ * @var array
+ */
+ private $response = array();
+
+ /**
* @var Route
*/
private $route;
@@ -89,6 +99,10 @@ public function __construct(array $data)
$this->description = $data['description'];
}
+ if (isset($data['return'])) {
+ $this->return = $data['return'];
+ }
+
$this->isResource = isset($data['resource']) && $data['resource'];
}
@@ -127,6 +141,14 @@ public function getInput()
}
/**
+ * @return string|null
+ */
+ public function getReturn()
+ {
+ return $this->return;
+ }
+
+ /**
* @return string
*/
public function getDescription()
@@ -183,6 +205,24 @@ public function setParameters(array $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
*/
public function setRoute(Route $route)
@@ -228,6 +268,10 @@ public function toArray()
$data['requirements'] = $requirements;
}
+ if ($response = $this->response) {
+ $data['response'] = $response;
+ }
+
return $data;
}
}
@@ -223,7 +223,7 @@ protected function extractData(ApiDoc $annotation, Route $route, \ReflectionMeth
// doc
$annotation->setDocumentation($this->getDocCommentText($method));
- // input
+ // input (populates 'parameters' for the formatters)
if (null !== $input = $annotation->getInput()) {
$parameters = array();
@@ -244,6 +244,20 @@ protected function extractData(ApiDoc $annotation, Route $route, \ReflectionMeth
$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) {
@@ -85,6 +85,22 @@ protected function renderOne(array $data)
}
}
+ 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;
}
@@ -35,10 +35,10 @@ public function supports($input)
try {
if ($meta = $this->factory->getMetadataForClass($input)) {
return true;
- }
+ }
} catch (\ReflectionException $e) {
}
-
+
return false;
}
@@ -81,7 +81,6 @@ protected function getDescription($className, $propertyName)
//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;
}
@@ -22,7 +22,7 @@ public function testAll()
$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));
@@ -100,4 +100,15 @@ public function zActionWithQueryParamAction()
public function jmsInputTestAction()
{
}
+
+ /**
+ * @ApiDoc(
+ * description="Testing return",
+ * return="dependency_type"
+ * )
+ */
+ public function jmsReturnTestAction()
+ {
+ }
+
}
@@ -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 }
@@ -186,6 +186,19 @@ public function testFormat()
* 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._
@@ -216,6 +216,20 @@ public function testFormat()
),
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}',
'requirements' =>
@@ -226,7 +240,7 @@ public function testFormat()
'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 @@ public function testFormat()
'id' => array('type' => '', 'description' => '', 'requirement' => '\d+')
),
),
- 6 =>
+ 7 =>
array(
'method' => 'GET',
'uri' => '/z-action-with-query-param',

0 comments on commit cbdddfe

Please sign in to comment.