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.cc/" } } 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.