public function getDocOutput(Parser $parser)
{
$fieldDocs = array();
$rClass = new \ReflectionClass($this);
$rProperties = $rClass->getProperties(\ReflectionProperty::IS_PUBLIC);
foreach ($rProperties as $rProperty) {
/*
* Ignores writing any model property with 'internal' or 'system' options
*/
if (in_array('internal', ReflectionHelper::getDocDirective($rProperty->getDocComment(), 'field')) || in_array('system', ReflectionHelper::getDocDirective($rProperty->getDocComment(), 'field'))) {
continue;
}
$varType = 'unknown';
// Pulls out the type following the pattern @var <TYPE> from the doc comments of the property
$varDocs = ReflectionHelper::getDocDirective($rProperty->getDocComment(), 'var');
if (!empty($varDocs)) {
$varType = $varDocs[0];
}
$fieldDoc = array('name' => $rProperty->getName(), 'type' => $varType, 'doc' => $parser->parse(ReflectionHelper::getDocText($rProperty->getDocComment())));
$fieldDocs[] = $fieldDoc;
}
return array('name' => get_called_class(), 'fielddocs' => $fieldDocs);
}
/**
* todo: docs
*
* @param Parser $parser
*
* @endpoint ignore
* @return array
*/
public function getDocJSON(Parser $parser)
{
$myClass = get_called_class();
$rClass = new \ReflectionClass($myClass);
$this->configureMiddlewares($this->middlewares);
$doc = array();
$doc['name'] = $this->documentationName;
$doc['description'] = $parser->parse(ReflectionHelper::getDocText($rClass->getDocComment()));
// Adding documentation for custom controller actions
$rMethods = $rClass->getMethods(\ReflectionMethod::IS_PUBLIC);
foreach ($rMethods as $rMethod) {
// If there is a '@endpoint ignore' property, the function is not served as an endpoint
if (in_array('ignore', ReflectionHelper::getDocDirective($rMethod->getDocComment(), 'endpoint'))) {
continue;
}
$methodDoc = array();
$methodDoc['InternalMethodName'] = $rMethod->name;
if (strpos($rMethod->name, 'get', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 3);
$methodDoc['HTTPMethod'] = 'GET';
} elseif (strpos($rMethod->name, 'put', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 3);
$methodDoc['HTTPMethod'] = 'PUT';
} elseif (strpos($rMethod->name, 'post', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 4);
$methodDoc['HTTPMethod'] = 'POST';
} elseif (strpos($rMethod->name, 'delete', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 6);
$methodDoc['HTTPMethod'] = 'DELETE';
} else {
continue;
}
$action = strtolower($methodDoc['MethodName']);
$methodDoc['URI'] = "/{$this->base}" . (empty($action) ? '' : "/{$action}");
$methodDoc['Synopsis'] = $parser->parse(ReflectionHelper::getDocText($rMethod->getDocComment()));
$methodDoc['parameters'] = $this->getDocParameters($rMethod);
if (empty($methodDoc['MethodName'])) {
$methodDoc['MethodName'] = ucwords($this->base);
}
// Allow controller middlewares to modify the documentation for this method
if (!empty($this->middlewares)) {
$middleware = reset($this->middlewares);
$middleware->documentMethod($rClass, $rMethod, $methodDoc);
}
if (!empty($methodDoc)) {
$doc['methods'][] = $methodDoc;
}
}
foreach (ReflectionHelper::getDocDirective($rClass->getDocComment(), 'docs-attach-model') as $includeModelClass) {
/**
* @var $model \MABI\Model
*/
$model = call_user_func($includeModelClass . '::init', $this->getApp());
$doc['models'][] = $model->getDocOutput($parser);
}
return $doc;
}
/**
* todo: docs
*
* @param Parser $parser
*
* @endpoint ignore
* @return array
*/
public function getDocJSON(Parser $parser)
{
$doc = parent::getDocJSON($parser);
$rClass = new \ReflectionClass(get_called_class());
foreach ($doc['methods'] as $k => $methodDoc) {
if ($methodDoc['InternalMethodName'] == 'get') {
$doc['methods'][$k]['MethodName'] = 'Get Full Collection';
} elseif ($methodDoc['InternalMethodName'] == 'post') {
$doc['methods'][$k]['MethodName'] = 'Add to Collection';
} elseif ($methodDoc['InternalMethodName'] == 'put') {
$doc['methods'][$k]['MethodName'] = 'Replace Full Collection';
} elseif ($methodDoc['InternalMethodName'] == 'delete') {
$doc['methods'][$k]['MethodName'] = 'Delete Full Collection';
}
}
$methodDoc = $this->getRestMethodDocJSON($parser, 'Get Resource', 'GET', "/{$this->base}/:id", $rClass, '_restGetResource');
if (!empty($methodDoc)) {
$doc['methods'][] = $methodDoc;
}
$methodDoc = $this->getRestMethodDocJSON($parser, 'Update Resource', 'PUT', "/{$this->base}/:id", $rClass, '_restPutResource');
if (!empty($methodDoc)) {
$doc['methods'][] = $methodDoc;
}
$methodDoc = $this->getRestMethodDocJSON($parser, 'Delete Resource', 'DELETE', "/{$this->base}/:id", $rClass, '_restDeleteResource');
if (!empty($methodDoc)) {
$doc['methods'][] = $methodDoc;
}
// Add documentation for custom rest actions
$rMethods = $rClass->getMethods(\ReflectionMethod::IS_PUBLIC);
foreach ($rMethods as $rMethod) {
$docComment = $rMethod->getDocComment();
// If there is a '@endpoint ignore' property, the function is not served as an endpoint
if (in_array('ignore', ReflectionHelper::getDocDirective($docComment, 'endpoint'))) {
continue;
}
$methodDoc = array();
$methodDoc['InternalMethodName'] = $rMethod->name;
if (strpos($rMethod->name, 'restGet', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 7);
$methodDoc['HTTPMethod'] = 'GET';
} elseif (strpos($rMethod->name, 'restPut', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 7);
$methodDoc['HTTPMethod'] = 'PUT';
} elseif (strpos($rMethod->name, 'restPost', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 8);
$methodDoc['HTTPMethod'] = 'POST';
} elseif (strpos($rMethod->name, 'restDelete', 0) === 0) {
$methodDoc['MethodName'] = substr($rMethod->name, 10);
$methodDoc['HTTPMethod'] = 'DELETE';
} else {
continue;
}
$action = strtolower($methodDoc['MethodName']);
$methodDoc['URI'] = "/{$this->base}/:id/{$action}";
$methodDoc['Synopsis'] = $parser->parse(ReflectionHelper::getDocText($docComment));
$methodDoc['parameters'][] = array('Name' => 'id', 'Required' => 'Y', 'Type' => 'string', 'Location' => 'url', 'Description' => 'The id of the resource');
$methodDoc['parameters'] = array_merge($methodDoc['parameters'], $this->getDocParameters($rMethod));
// Allow controller middlewares to modify the documentation for this method
if (!empty($this->middlewares)) {
$middleware = reset($this->middlewares);
$middleware->documentMethod($rClass, $rMethod, $methodDoc);
}
if (!empty($methodDoc)) {
$doc['methods'][] = $methodDoc;
}
}
return $doc;
}
