Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

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 update

Usage

<?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.php

Available 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

About

Generate documentation for php API based application. No dependency. No framework required.

Resources

License

Packages

No packages published
You can’t perform that action at this time.