README

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

• Requirements
• Installation
• Usage
• Available Methods
• Preview
• Tips
• Known issues
• TODO

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