Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Scribd
Upload
169 views

Api Doc

apiDoc is a node module that creates documentation pages for RESTful APIs from source code comments. It parses API descriptions, parameters, errors and examples from block comments to generate HTML documentation. The documentation includes version history to allow developers to see changes made between API versions. apiDoc is open source, supports custom templates, and can generate documentation for APIs in any programming language.

Uploaded by

Hồ Vũ Hoàng
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
169 views

Api Doc

apiDoc is a node module that creates documentation pages for RESTful APIs from source code comments. It parses API descriptions, parameters, errors and examples from block comments to generate HTML documentation. The documentation includes version history to allow developers to see changes made between API versions. apiDoc is open source, supports custom templates, and can generate documentation for APIs in any programming language.

Uploaded by

Hồ Vũ Hoàng
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 24

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

You might also like