APIDOC

Inline Documentation for RESTful web APIs

Introduction with a small example.

http://apidocjs.com
 What does apiDoc ?

apiDoc
creates a Documentation HTML-Page
use API-Descriptions from your source code

For who ?

apiDoc can be used with any programming language, that allow

block documentation:

/**
* This is a comment.
*/
 Where i find apiDoc ?

apiDoc is Open Source and distributed over NPM and github

Visit: http://apidocjs.com

Special functions

apiDoc
support own created Templates
includes History
compare old and new API-Method Versions
allows frontend Developer to see what changed
support Inherit
reuse of Documentation parts
extendable
you can create your own Documentation Methods
 Ok, let us begin...

apiDoc is a node module, so install Node.js first:

http://nodejs.org

Node.js includes npm, a package manager for node.

Install apiDoc
[sudo] npm install -g apidoc

We install apiDoc global, so you can access it from everywhere.

EXAMPLE PROJECT
We use a simple static JavaScript example.
We ignore routing, validation or database operations.

This are only small parts of apiDocs functions, for all visit http://apidocjs.com
There is also a complex example: http://apidocjs.com/#example-full
Create a new directory my_project.
Within that dir create a file example.js.

example.js
var currentUser = {
name: 'Mary'
};

function getUser() {
return { code: 200, data: currentUser };
}

function setName(name) {
if(name.length === 0) {
return { code: 404, message: 'NameEmptyError' };
}
currentUser.name = name;
return { code: 204 };
}
 A basic doc

Above function getUser we place a basic documentation block

/**
* @api {get} /user Request User information
* @apiName GetUser
* @apiGroup User
*/
function getUser() {
return { code: 200, data: currentUser };
}

This 3 parameters are required!

@api describes the path of the Method that clients call.
@apiName is a unique Name, you can name as you want, for simplicity i prefer
Type of Method + Name of Method e.g. {get} and /user => GetUser.
@apiGroup is the name of the group to which this method belongs. The group will be
used for Navigation.
From command line run within my_project directory:
apidoc

By default apiDoc search for all .jjs files in current directory and sub directories.
You can change the includeFilter, call apidoc -h for details.

apiDoc created a new HTML-Page in directory doc.

Open doc/index.html in your Browser

We see the rudimentary Webpage, with Navigation left and Content right.
We have a group User and within that group an API-Method GET /user
 Describe the API-Answer

Now we add success return parameters

/**
* @api {get} /user Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiSuccess {String} name The users name.
*/
function getUser() {
return { code: 200, data: currentUser };
}

Run apiDoc again, it will overwrite the doc Directory

apidoc
Now we have a little more Information and see what GET /user returns on a
successful reply Success 200.
 Add a Version and example Code

We add a Version (Format major.minor.patch, see http://semver.org for details)

and we add an example code, that shows what will be return in case of success
/**
* @api {get} /user Request User information
* @apiName GetUser
* @apiGroup User
* @apiVersion 0.1.0
*
* @apiSuccess {String} name The users name.
*
* @apiSuccessExample Example data on success:
*{
* name: 'Paul'
*}
*/
function getUser() {
return { code: 200, data: currentUser };
}
In the right dropdown box we see now the Version 0.1.0 and under Success 200
our integrated example.
VERSIONING
If you work in a Team and some Programmer work an the API backend and some on
Frontend Client, it is important to know what changed in a new Release.
Especially during developing an Application, many things can change.
 An API Method change

Create a new file _apidoc.js.

Put only the documentation Block from getUser in that file:

_apidoc.js
/**
* @api {get} /user Request User information
* @apiName GetUser
* @apiGroup User
* @apiVersion 0.1.0
*
* @apiSuccess {String} name The users name.
*
* @apiSuccessExample Example data on success:
*{
* name: 'Paul'
*}
*/

_apidoc.js will be our history file and contains old documentation blocks.
Now we change the documentation block in example.js

example.js
/**
* @api {get} /user Request User information
* @apiName GetUser
* @apiGroup User
* @apiVersion 0.2.0
*
* @apiSuccess {String} name The users name.
* @apiSuccess {Number} age Calculated age from Birthday
*
* @apiSuccessExample Example data on success:
*{
* name: 'Paul',
* age: 27
*}
*/
function getUser() {
return { code: 200, data: currentUser };
}
After call apidoc and open doc/index.html you see now Version 0.2.0 with the
Field age and the changed example.
And now the magic...
Select from Dropdown 0.2.0 the Version 0.1.0.
You see now a comparison from the 2 Versions. Green marked content indicates the
Fields that are added to Version 0.2.0.
In the future, when you made more changes to an API-Method, simply copy and add
the complete documentation block to the history file _apidoc.js.
Leave the old blocks as they are.
Then you have a Documentation where everybody can see any change of your API.
PARAMS AND ERRORS
We take now a quick look at how to add Parameters, that an API-Method need and
how we return errors.
We add now a documentation to our second function setName.

example.js
/**
* @api {put} /user Change User
* @apiName PutUser
* @apiGroup User
* @apiVersion 0.1.0
*
* @apiParam {String} name New name of the user
*
* @apiError NameEmptyError The name was empty. Minimum of <code>1</code> character is required.
*/
function setName(name) {
if(name.length === 0) {
return { code: 404, message: 'NameEmptyError' };
}
currentUser.name = name;
return { code: 204 };
}
You will see now the new Change User entry in navigation and the content for the
API-Method.
Thank you and have a productive use !
For more Information visit http://apidocjs.com

Author: Peter Rottmann

peter@apidocjs.com