apiDoc Introduction

3,379 views

Published on

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

Published in: Technology
1 Comment
1 Like
Statistics
Notes
No Downloads
Views
Total views
3,379
On SlideShare
0
From Embeds
0
Number of Embeds
74
Actions
Shares
0
Downloads
16
Comments
1
Likes
1
Embeds 0
No embeds

No notes for slide

apiDoc Introduction

  1. 1. APIDOCInline Documentation for RESTful web APIsIntroduction with a small example.http://apidocjs.com
  2. 2. What does apiDoc ?apiDoc… creates a Documentation HTML-Page… use API-Descriptions from your source codeFor who ?apiDoc can be used with any programming language, that allowblock documentation:/*** This is a comment.*/
  3. 3. Where i find apiDoc ?apiDoc is Open Source and distributed over NPM and githubVisit: http://apidocjs.comSpecial functionsapiDoc… 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
  4. 4. Ok, let us begin...apiDoc is a node module, so install Node.js first:http://nodejs.orgNode.js includes „npm“, a package manager for node.Install apiDoc[sudo] npm install -g apidocWe install apiDoc global, so you can access it from everywhere.
  5. 5. EXAMPLE PROJECTWe 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.comThere is also a complex example: http://apidocjs.com/#example-full
  6. 6. Create a new directory „my_project“.Within that dir create a file „example.js“.example.jsvar 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 };}
  7. 7. A basic docAbove „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 beused for Navigation.
  8. 8. 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
  9. 9. Open „doc/index.html“ in your BrowserWe see the rudimentary Webpage, with Navigation left and Content right.We have a group „User“ and within that group an API-Method „GET /user“
  10. 10. Describe the API-AnswerNow 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 };}apidocRun apiDoc again, it will overwrite the „doc“ Directory
  11. 11. Now we have a little more Information and see what „GET /user“ returns on asuccessful reply „Success 200“.
  12. 12. Add a Version and example CodeWe 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 };}
  13. 13. In the right dropdown box we see now the Version „0.1.0“ and under „Success 200“our integrated example.
  14. 14. VERSIONINGIf you work in a Team and some Programmer work an the API backend and some onFrontend Client, it is important to know what changed in a new Release.Especially during developing an Application, many things can change.
  15. 15. An API Method changeCreate 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.
  16. 16. 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 };}
  17. 17. After call „apidoc“ and open „doc/index.html“ you see now Version „0.2.0“ with theField „age“ and the changed example.
  18. 18. And now the magic...
  19. 19. Select from Dropdown „0.2.0“ the Version „0.1.0“.You see now a comparison from the 2 Versions. Green marked content indicates theFields that are added to Version „0.2.0“.
  20. 20. In the future, when you made more changes to an API-Method, simply copy and addthe 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.
  21. 21. PARAMS AND ERRORSWe take now a quick look at how to add Parameters, that an API-Method need andhow we return errors.
  22. 22. 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 };}
  23. 23. You will see now the new „Change User“ entry in navigation and the content for theAPI-Method.
  24. 24. Thank you and have a productive use !For more Information visit http://apidocjs.comAuthor: Peter Rottmannpeter@apidocjs.com

×