Vegas CMF API Documentor
, (*1)
Usage
Add vegas-cmf/apidoc to composer.json dependencies
"vegas-cmf/apidoc" : "1.0.*"
and run composer update, (*2)
php composer.phar update
Create CLI task which extends \Vegas\ApiDoc\Task\GeneratorTaskAbstract.php
mkdir app/tasks
touch app/tasks/ApidocTask.php
//app/tasks/ApidocTask.php
use Vegas\Cli\Task\Option;
use Vegas\Mvc\View;
class ApidocTask extends \Vegas\ApiDoc\Task\GeneratorTaskAbstract
{
protected function getView()
{
$view = new View($this->di->get('config')->application->view->toArray());
$view->setDI($this->di);
return $view;
}
protected function getOutputPath()
{
return APP_ROOT . '/public/apiDoc/';
}
protected function getLayoutFilePath()
{
return APP_ROOT . '/app/layouts/partials/apiDoc/layout';
}
protected function getInputPath()
{
return APP_ROOT . '/app/modules';
}
}
Add annotations to controllers classes
<?php
namespace ApiTest\Controllers;
use ApiTest\Services\Exception\ApiException;
use Vegas\Mvc\Controller\ControllerAbstract;
use Phalcon\Mvc\Dispatcher;
/**
* @api(
* name='Test',
* description='Test API',
* version='1.0.0'
* )
*/
class TestController extends ControllerAbstract
{
/**
* @api(
* method='GET',
* description='Returns Test object',
* name='Get test',
* url='/api/test/{id}',
* params=[
* {name: 'id', type: 'string', description: 'Test ID'}
* ],
* headers=[
* {name: 'HTTP_X_AUTH', description: 'Authentication token'}
* ],
* requestFormat='JSON',
* requestContentType='application/json',
* request={
* {name: 'id', type: 'MongoId', description: 'ID of something'}
* },
* requestExample='{
* "id": "123"
* }',
* responseFormat='JSON',
* responseContentType='application/json',
* response=[
* {name: 'id', type: 'MongoId', description: 'Test ID'},
* {name: 'name', type: 'string', description: 'Foo name'}
* ],
* responseCodes=[
* {code: 111, description: 'Connection refused'},
* {code: 200, description: 'OK'},
* {code: 300, description: 'Found'},
* {code: 404, description: 'Record not found'},
* {code: 500, description: 'Application error'}
* ],
* responseExample='{
* "id": "123",
* "name": "Test"
* }'
* )
*/
public function getAction()
{
try {
if (!$this->request->get('id')) {
throw new ApiException();
}
return $this->jsonResponse(
[
'id' => '123',
'name' => 'Test 1'
]
);
} catch (ApiException $e) {
$response = $this->jsonResponse('');
$response->setStatusCode(404, 'Record not found');
return $response;
} catch (\Exception $e) {
$response = $this->jsonResponse('');
$response->setStatusCode(500, 'Application error');
return $response;
}
}
/**
* @api(
* method='GET',
* description='Returns list of tests objects',
* name='Get tests',
* url='/api/test',
* headers=[
* {name: 'HTTP_X_AUTH', description: 'Authentication token'}
* ],
* responseCodes=[
* {code: 500, description: 'Unknown error'}
* {code: 200, description: 'Ok'}
* ],
* requestFormat='JSON',
* requestContentType='application/json',
* request=''
* requestExample='',
* responseFormat='JSON',
* responseContentType='application/json',
* response=[
* {
* {name: 'id', type: 'MongoId', description: 'Test ID'},
* {name: 'name', type: 'string', description: 'Test name'}
* },
* {
* {name: 'id', type: 'MongoId', description: 'Test ID'},
* {name: 'name', type: 'string', description: 'Test name'}
* }
* ],
* responseExample='[
* {
* "id": "123",
* "name": "Test 1"
* },
* {
* "id": "124",
* "name": "Test 2"
* }
* ]'
* )
* @return null|\Phalcon\Http\ResponseInterface
*/
public function listAction()
{
try {
return $this->jsonResponse(
[
'id' => '123',
'name' => 'Test 1'
],
[
'id' => '124',
'name' => 'Test 2'
]
);
} catch (\Exception $e) {
$response = $this->jsonResponse('');
$response->setStatusCode(500, 'Application error');
return $response;
}
}
}
Available parameters:
Class
name Name of endpoint, (*3)
description Detailed description of the API endpoint, (*4)
version API version, (*5)
Method
name Name of API method, (*6)
description Detailed description of the API method, (*7)
method Determines HTTP method (POST, GET, ...), (*8)
url Request path, (*9)
params Describes parameters passed to API method, (*10)
headers Describes headers passed in request e.g. for Authorization, (*11)
request Describes request, (*12)
requestContentType Determines request Content-Type, (*13)
requestFormat Determines request format, (*14)
requestExample Example of request body, (*15)
response Describes response, (*16)
responseContentType Determines response Content-Type, (*17)
responseFormat Determines response format, (*18)
responseExample Example of response body, (*19)
responseCodes Describes response status codes, (*20)
Create documentation layout ( you can use sample layout from tests/fixtures/app/layouts/partials/apiDoc directory ) and prepare output directory
mkdir app/layouts/partials -p
touch cp -R vendor/vegas-cmf/apidoc/tests/fixtures/app/layouts/partials/apiDoc app/layouts/partials/.
mkdir public/apiDoc
Run CLI Task to generate documentation
php cli/cli.php app:apidoc generate
See sample http://jsbin.com/xeyetevuro/1, (*21)
Wallogit.com
