How to create beautiful API documentation with apiDoc.js

selection_849This is some explanation for making any changes, how to create the API Doc, etc. ApiDoc website:

1. install node.js, node packagemanager, and nodejs-legacy:

2.Install nodejs-legacy: `sudo apt-get install nodejs-legacy` (for explanation of *why* this step is necessary, see here:

3.Install apidoc : `sudo npm install apidoc -g` 4. Annotate according to apidoc instructions and following the example of `` in the BPN repo. Sample annotation:

@api {get} /bpn/rest/bionewsRss Get Bionews Search Results
@apiName bionewsRss
@apiGroup Search
@apiVersion 1.0.0
@apiParamExample Example:
@apiParam {String} searchId id of a previous search (Optional)
@apiParam {String[]} source type of Bionews source: companies, syndicated, twitter, other (Optional -- default = all)
@apiParam {Integer} count maximum # of items to return (Optional -- default = 10)
@GET @Produces({ "text/xml" })
public String get(@QueryParam("searchId") String searchId, @QueryParam("source") List source, @QueryParam("count") @DefaultValue("10") int count) {

//function body goes here….

How to generate the docs:  once the apiDoc node package is installed, run this command from the root directory of : apidoc  -o /path/to/doc/output. Alternatively, the `-i` flag allows you to specify the input directory. For a full list of features, see `apidoc –help`. Screenshot: Lastly, review the end result, and you may want to grep search & replace if you still see junk in the final product, perhaps due to misconfigured annotation.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s