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.