Servage Magazine

A good documentation is a requirement for a good API. If you make a good public API but the documentation is lacking, your API will not see as big of an adoption as it would with a well-written developer-friendly API. Let’s have a look at how to write documentation for a PHP-based API and also what a documentation should have, no matter what language it is written in.

Writing a Good API Documentation

Before looking at how to write API documentation, let’s consider the things a documentation should have. We will be focusing on a REST API, although the points mentioned usually apply to other types of APIs as well.

First of all, every API endpoint should be listed. An endpoint is a URI that API clients send requests to, such as “GET /books/1” or “POST /reviews”. Each endpoint should contain a list of form fields and query parameters that the endpoint accepts. For instance, a “POST /reviews” request should contain a review field which contains the content of the review.

It is also recommended to be verbose by including a full example request with all the required form fields. To make things even better, you can also include an example response. If you version your API, you should make it clear for which API version the request and response is meant for. The parameters and response might be different depending on which version of the API is used.

Writing Documentation with apiDoc

Let’s have a look at one tool for documenting APIs. We will be focusing on PHP this time, but apiDoc has support for a wide variety of languages.

There’s three things you need to do to generate documentation with apiDoc. The first is to install the tool using npm: “npm install -g apidoc”.

The next step is to write the documentation. In apiDoc this is done using annotations, sometimes also called PHPDoc. In PHP, you create an annotation using “/**” to start the annotation and  “*/” to end it. There are a few annotations each endpoint should have, such as @api, @apiName, and @apiGroup. @api defines the HTTP method, URI and a name for the request, @apiName is a name for the action and @apiGroup groups similar endpoints together. Here is an example of a simple apiDoc annotation: “/** @api {get} /reviews/:id Get a review by ID @apiName GetReview @apiGroup Review */”. Typically you want to place these one per line to make your code more readable. There are many other annotations you can use to add a longer description, error and success responses and much more. You can find the complete list at www.apidocjs.com.

When you’re done with annotating your code, you can generate the documentation by running “apidoc -i src/ -o docs/”. This will generate a beautiful and easy-to-read website for your documentation. To view it, open the index.html file in the docs directory. If you want your documentation to be publicly available, you can upload the directory to your web server.