Slide 1

Slide 1 text

APIDOC Inline Documentation for RESTful web APIs Introduction with a small example. http://apidocjs.com

Slide 2

Slide 2 text

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. */

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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.

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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 }; }

Slide 7

Slide 7 text

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.

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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“

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

Now we have a little more Information and see what „GET /user“ returns on a successful reply „Success 200“.

Slide 12

Slide 12 text

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 }; }

Slide 13

Slide 13 text

In the right dropdown box we see now the Version „0.1.0“ and under „Success 200“ our integrated example.

Slide 14

Slide 14 text

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.

Slide 15

Slide 15 text

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.

Slide 16

Slide 16 text

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 }; }

Slide 17

Slide 17 text

After call „apidoc“ and open „doc/index.html“ you see now Version „0.2.0“ with the Field „age“ and the changed example.

Slide 18

Slide 18 text

And now the magic...

Slide 19

Slide 19 text

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“.

Slide 20

Slide 20 text

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.

Slide 21

Slide 21 text

PARAMS AND ERRORS We take now a quick look at how to add Parameters, that an API-Method need and how we return errors.

Slide 22

Slide 22 text

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 1 character is required. */ function setName(name) { if(name.length === 0) { return { code: 404, message: 'NameEmptyError' }; } currentUser.name = name; return { code: 204 }; }

Slide 23

Slide 23 text

You will see now the new „Change User“ entry in navigation and the content for the API-Method.

Slide 24

Slide 24 text

Thank you and have a productive use ! For more Information visit http://apidocjs.com Author: Peter Rottmann [email protected]