Share
Embed
API Documentation
Inline Documentation for RESTful web APIs
apiDoc introduction with a small example.
http://apidocjs.com
Peter Rottmann
June 08, 2013
Transcript
24 slides
-
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. -
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“. From command line run within „my_project“ directory: apidoc -
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 }; } apidoc Run apiDoc again, it will overwrite the „doc“ Directory -
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. -
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 [email protected]