Documenting APIs at QICE

The Backstory: 

At QICE, We develop custom API Backends for Mobile Applications almost all the time. While developing APIs initially, we would use a tool like Hackpad or Google Docs to document the project’s API.

We soon found this was not feasible for couple of reasons :

  • It was tedious for our API team to document the API. Not only did they have to document their code, but they also had to document the API, in a totally different tool.
  • Handling versioning of the API in the document was unmanageable.
How we solved it: 
As such, we started looking for simpler solutions to document our APIs. After much discussion, we decided on using apiDocJS. apiDocJS scans your projects for API Annotations and generates documentation for you.

Installing apiDocJS is simple as

npm install apidoc -g

apiDocJS supports mainly Javadoc style commenting, but for languages not using Javadoc style – using their multi-line comment code should work. At QICE, we build our APIs on top of Laravel and so follow the Javadoc style of commenting the code.

Here is how one of our method’s comment looks for example:

/**
* @api {post} /bookmarkEvent/ Bookmark Event
* @apiName bookmarkEvent
* @apiVersion 1.0.0
* @apiGroup Events
* @apiDescription This method will add or remove event from the users bookmark list.
*
* @apiHeader {String} Authorization User Unique Authorization.
* @apiParam {Number} event_id Unique Event ID.
* @apiSuccess {Boolean} error Depending on the result. error parameter will be returned.
* true indicates failure and false indicates success.
* @apiSuccess {String} message message key will contain message according to the result.
*/

Once we are done commenting our APIs, we then run the following command which generates the HTML documents for APIs.

apidoc -i project/ -o docs/

The above command looks for files inside the “project” folder and generates the document inside a folder named “docs” which is placed inside the project folder.

After generating, here’s the output for the method given above

api-method-output

 Solving our problems:
 

apiDocJS solves our major issue of writing our API documentation in a different tool. Now, all we have to do is run a command to generate our documentation.

As for our second issue with versioning, we use @apiVersion tag to bump up the version and notify the users of API ( usually, mobile developers) about the change in API.

Limitations:

There are albeit a few issues with apiDocJS. For example, if you want to compare your API with the previous versions – you will have to create an old file with the name _filename.php – which adds unnecessary files to the project. For us, this wasn’t a deal breaker as we rarely need compare previous versions of API ( and use git diff whenever needed)

While there are lots of tools out there in the market which do a lot more than apiDocJS does – we found apiDocJS more suited to our needs and something that could be integrated with less training overhead.