PHP Rest API Documentation Using APIDoc

This tutorial help to create REST API docs using APIDOc. The apiDoc creates a documentation using API annotations from your PHP source code.There are a lot of application are running into micro services and Rest services.

APIDOC is a npm package that will create API documentation.We are using nodejs and npm for apidoc as a dependency, I am using PHP Laravel API as a source API to create API docs.

The PHP annotations for API Documentation –

/**
 * @api {get} /employees Request User information
 * @apiVersion 0.1.0
 * @apiName AllEmployee
 * @apiGroup Employee
 *
 * @apiSuccess {String} resp All employee data
 * @apiError {json} resp  The error of about failed rest api.
 */

You need to add above notation for each method which want to display into apidocs view.

• @api {get} /employees : This will use to define rest end points.
• @apiVersion : This will use to define API version.
• @apiName : This will use to define controller method name that will handle by endpoint.
• @apiGroup : This will use to define rest api group name.
• @apiSuccess : This will use to define response varaible name with type.
• @apiError : This will use to define error response varaible with type.
• @apiParam /employees : This will use to define parameter for rest api.
• @apiSampleRequest : This is use to enable tryout feature.

Install APIDoc Using npm

Let’s install apiDoc globally using -g option:

npm install apidoc -g

Simple Project To Create API Documentaion

Let’s create simple api project to create documentation.

Step 1: Created folder ‘apidocs’ into xampp/htdocs/.
Step 2: Define apiDoc meta information, we will create apidoc.json file and added below meta information into this file –

{
  "name": "PHPFlow.com",
  "version": "0.1.0",
  "description": "Employee API Docs",
  "apidoc": {
    "title": "PHPFlow.com",
    "url" : "https://phpflow.com/"
  }
}

Step 3: Created two folder into ‘apidocs’ folder, The folder name is /source and others is /apidoc. The /source folder will have all .php files and /apidoc folder will have generated API docs files.

Step 4: Created a sample ApiController.php file and saved into /source folder, Added below code into this file –

namespace App\Http\Controllers;
 
use Log;
use Illuminate\Http\Request;
use Employee\Helpers\Helper;
use Validator;
 
class ApiController extends Controller
{
     /**
       * @api {post} /create Add record into employee table
       * @apiName create
       * @apiGroup Employee
       *
       * @apiParam {json} params required To add item into employee.
       *
       * @apiSuccess {json} Results Added employee information.
       * @apiError {json} Results Failed information.
       */     public function create(Request $request) {       
        $response = array();
        $parameters = $request->json()->all();
        try {
            //save data into mysql db
        } catch(Exception $ex) {
            Log::info('Unable to add data');
            Log::critical($ex);
            return Helper::jsonpError("Unable to add data", 400, 400);
        }
       
   }
     /**
       * @api {get} employee/:id Get employee information
       * @apiName getEmployee
       * @apiGroup Employee
       *
       * @apiParam {Number} id required The id of employee.
       *
       * @apiSuccess {json} Results The employee information.
       * @apiError {json} Results Unable to get employee information.
       */   public function getEmployee($id) {
       
        try {
            //get employee based on path id param
        } catch(Exception $ex) {
            Log::info('Unable to get employee information');
            Log::critical($ex);
            return Helper::jsonpError("Unable to get employee information", 400, 400);
        }
       
   }
}

You can generate API documentation using below command –
apidoc -i source/ -o apidoc/

Above command will create API docs structure into apidoc/ folder, We can change source path as per our need.

Now open http://localhost/apidocs/doc/ location path into browser.

How To enable TryOut Feature

You can also enable API Tryout feature using @apiSampleRequest annotation.

* @apiSampleRequest /employee/:id

You need to add base URi(http://dummy-api/api/v1) into apidoc.json file.

After any changes into annotation or meta information, You need to regenerate api docs using command.