php-apidoc
Generate documentation for php API based application. No dependency. No framework required.
Requirements
PHP >= 5.3.2
Installation
The recommended installation is via composer. Just add the following line to your composer.json:
{
...
"require": {
...
"crada/php-apidoc": "@dev"
}
}$ php composer.phar updateUsage
<?php
namespace Some\Namespace;
class User
{
/**
* @ApiDescription(section="User", description="Get information about user")
* @ApiMethod(type="get")
* @ApiRoute(name="/user/get/{id}")
* @ApiParams(name="id", type="integer", nullable=false, description="User id")
* @ApiParams(name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string','age':'integer'}}")
* @ApiReturnHeaders(sample="HTTP 200 OK")
* @ApiReturn(type="object", sample="{
* 'transaction_id':'int',
* 'transaction_status':'string'
* }")
*/
public function get()
{
}
/**
* @ApiDescription(section="User", description="Create's a new user")
* @ApiMethod(type="post")
* @ApiRoute(name="/user/create")
* @ApiParams(name="username", type="string", nullable=false, description="Username")
* @ApiParams(name="email", type="string", nullable=false, description="Email")
* @ApiParams(name="password", type="string", nullable=false, description="Password")
* @ApiParams(name="age", type="integer", nullable=true, description="Age")
*/
public function create()
{
}
}Create an apidoc.php file in your project root folder as follow:
# apidoc.php
<?php
use Crada\Apidoc\Builder;
use Crada\Apidoc\Exception;
$classes = array(
'Some\Namespace\User',
'Some\Namespace\OtherClass',
);
$output_dir = __DIR__.'/apidocs';
$output_file = 'api.html'; // defaults to index.html
try {
$builder = new Builder($classes, $output_dir, 'Api Title', $output_file);
$builder->generate();
} catch (Exception $e) {
echo 'There was an error generating the documentation: ', $e->getMessage();
}Then, execute it via CLI
$ php apidoc.phpAvailable Methods
Here is the list of methods available so far :
- @ApiDescription(section="...", description="...")
- @ApiMethod(type="(get|post|put|delete|patch")
- @ApiRoute(name="...")
- @ApiParams(name="...", type="...", nullable=..., description="...", [sample=".."])
- @ApiHeaders(name="...", type="...", nullable=..., description="...")
- @ApiReturnHeaders(sample="...")
- @ApiReturn(type="...", sample="...")
- @ApiBody(sample="...")
Preview
You can see a dummy generated documentation on http://calinrada.github.io/php-apidoc/
Tips
To generate complex object sample input, use the ApiParam "type=(object|array(object)|array)":
* @ApiParams(name="data", type="object", sample="{'user_id':'int','profile':{'email':'string','age':'integer'}}")Known issues
I don't know any, but please tell me if you find something. PS: I have tested it only in Chrome !
TODO
- Implement options for JSONP
- Implement "add fields" option