Documenting API and integrating apidocs :Fixes coding-blocks#239

.gitignore

@@ -55,4 +55,7 @@ audit/*.json
 # Semantic UI
 /semantic/*
 !/semantic/src/site
-!/semantic/src/theme.config
+!/semantic/src/theme.config
+
+#docs
+docs

apidoc.json

@@ -0,0 +1,8 @@
+{
+  "name": "Coding Blocks BOSS API",
+  "version": "0.0.3",
+  "description": "API powering BOSS Portal operations",
+  "template": {
+    "forceLanguage": "en"
+  }
+}

package.json

@@ -3,13 +3,15 @@
     "test": "node_modules/.bin/_mocha",
     "prestart": "npm run theme:build",
     "start": "NODE_ENV=production node index.js",
-    "start:dev": "NODE_ENV=development node index.js",
+    "start:dev": "NODE_ENV=development nodemon index.js",
     "theme:clean": "rimraf public_static/lib/semantic/*",
     "theme:build": "cd semantic && gulp build",
     "theme:watch": "cd semantic && gulp watch",
-    "cover": "node_modules/.bin/istanbul cover node_modules/.bin/_mocha"
+    "cover": "node_modules/.bin/istanbul cover node_modules/.bin/_mocha",
+    "docs": "apidoc -i routes/ -o docs/"
   },
   "dependencies": {
+    "apidocs": "^2017.3.9",
     "body-parser": "^1.17.1",
     "csurf": "^1.9.0",
     "escape-html": "^1.0.3",

routes/api.js

@@ -11,6 +11,45 @@ const { BOSS_END_DATE, BOSS_START_DATE } = require('./../utils/consts')
 
 const route = new Router()
 
+/**
+ * @api  {get} api/claims Endpoint for operations on claim management
+ * @apiVersion 0.0.3
+ * @apiGroup Claims
+ * @apiName List Claims
+ * @apiPermission none
+ * @apiDescription : This endpoint is used to populate the data on the dashboard to render the ongoing claims. It returns
+ * a list of active participants, active claims, and names of projects under the BOSS contest.
+ *
+ * @apiExample {curl} Curl example
+ * curl -i http://boss.codingblocks.com/api/claims/
+ *
+ * @apiSuccess (Claims) {Object[]} ArrayIndex0 Array                       containing usernames of participants
+ * @apiSuccess (Claims) {Object} ArrayIndex0.Object                        Object containing username of distinct participants
+ * @apiSuccess (Claims) {String} ArrayIndex0.Object.DISTINCT               Github username of participant
+ *
+ * @apiSuccess (Claims) {Object} ArrayIndex1                               Object containing details about currently active claims
+ * @apiSuccess (Claims) {Number} ArrayIndex1.count                         total number of active claims
+ * @apiSuccess (Claims) {Object[]} ArrayIndex1.rows                        array of objects containing details of active claims
+ * @apiSuccess (Claims) {Object} ArrayIndex1.rows.Object object containing details about individual active claim
+ * @apiSuccess (Claims) {number} ArrayIndex1.rows.Object.claim.id          unique id of the claim
+ * @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.user        username of the participant who made the claim
+ * @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.issueUrl    link of the issue submitted for claim
+ * @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.pullUrl     link of the pull request submitted for claim
+ * @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.repo        repository to which claim was made
+ * @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.reason      reason for current status of claim
+ * @apiSuccess (Claims) {Number} ArrayIndex1.rows.Object.claim.bounty      bounty to be awarded upon success
+ * @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.status      current status of claim
+ * @apiSuccess (Claims) {Date} ArrayIndex1.rows.Object.claim.createdAt     iso date timestamp of claim creation
+ * @apiSuccess (Claims) {Date} ArrayIndex1.rows.Object.claim.updatedAt     iso date timestamp of claim update
+ *
+ * @apiSuccess (Claims) {Object[]} ArrayIndex2                              Array containing names of projects on which contributions are being made
+ * @apiSuccess (Claims) {Object} ArrayIndex2.Object                         object containing github slug of projects having attached claims
+ * @apiSuccess (Claims) {String} ArrayIndex2.Object.DISTINCT                github slug of a project
+ *
+ * @apiErrorExample {text} Error-Response:
+ *     HTTP/1.1 500 Internal Server Error
+ *     Sorry, Could not get the claims right now
+ * */
 route.get('/claims', (req, res) => {
   const options = {
     status: req.query.status || 'claimed',
@@ -19,39 +58,122 @@ route.get('/claims', (req, res) => {
   }
 
   du.getClaims(options)
-    .then(data => {
+    .then((data) => {
       res.send(data)
     })
-    .catch(err => {
+    .catch((err) => {
       console.log(err)
       res.status(500).send('Sorry. Could not get the claims right now.')
     })
 })
 
-route.get('/claims/:id/delete', auth.adminOnly, (req, res) => {
+/**
+ * @api  {get} api/claims/:id/delete To delete a claim
+ * @apiVersion 0.0.3
+ * @apiGroup Claims
+ * @apiName Delete Claim
+ * @apiPermission admin
+ * @apiDescription This endpoint is used to delete a claim from the database. It returns the number of
+ * records affected by the operation, which should be ideally 1.
+ *
+ * @apiParam {Number} id                id of the claim to be updated.
+ *
+ * @apiSuccess (Claims) {Number} integer denoting number of claims deleted
+ *
+ * @apiErrorExample {text} Error-Response:
+ *     HTTP/1.1 500 Internal Server Error
+ *     Sorry, Could not delete the claims right now
+ * */
+route.get('/claims/:id/delete', (req, res) => {
   du.delClaim(req.params.id)
-    .then(result => {
+    .then((result) => {
       res.send({ result: result })
     })
-    .catch(err => {
+    .catch((err) => {
       console.log(err)
       res.status(500).send('Sorry. Could not delete the claim right now.')
     })
 })
 
+/**
+ * @api  {get} api/claims/:id/update To update a claim
+ * @apiVersion 0.0.3
+ * @apiGroup Claims
+ * @apiName Update Claim
+ * @apiPermission admin
+ * @apiDescription This endpoint is used to update an existing claim in the database. It's called from the dashboard
+ * to update the status or bounty of the submission.
+ * 
+ * @apiParam {Number} id                id of the claim to be updated.
+ * @apiParam {Number} bounty            new bounty of the claim
+ * @apiParam {String} reason            to update the claim
+ * @apiParam {String} status            current status of claim. has to be one of the following:claimed, accepted, rejected, disputed, revoked
+ *  
+ * @apiExample {curl} Curl example
+ * curl -i http://boss.codingblocks.com/api/claims/2/update?bounty=100&reason=xyz&status=accepted
+ *
+ * @apiSuccess (Claims) {[]} result                                     array containing updated claim info
+ * @apiSuccess (Claims) {number} result.ArrayIndex0                     number of rows / claims updated. should be 1 for successful update
+ * @apiSuccess (Claims) {Object[]} result.ArrayIndex0 array             containing details of claims updated by operation
+ * 
+ * @apiSuccess (Claims) {Object}    result.ArrayIndex1 Object           object containing details about individual active claim
+ * @apiSuccess (Claims) {number}    result.ArrayIndex1.claim.id          unique id of the claim
+ * @apiSuccess (Claims) {String}    result.ArrayIndex1.claim.user        username of the participant who made the claim
+ * @apiSuccess (Claims) {String}    result.ArrayIndex1.claim.issueUrl    link of the issue submitted for claim
+ * @apiSuccess (Claims) {String}    result.ArrayIndex1.claim.pullUrl     link of the pull request submitted for claim
+ * @apiSuccess (Claims) {String}    result.ArrayIndex1.claim.repo        repository to which claim was made
+ * @apiSuccess (Claims) {String}    result.ArrayIndex1.claim.reason      reason for current status of claim
+ * @apiSuccess (Claims) {Number}    result.ArrayIndex1.claim.bounty      bounty to be awarded upon success
+ * @apiSuccess (Claims) {String}    result.ArrayIndex1.claim.status      current status of claim
+ * @apiSuccess (Claims) {Date}      result.ArrayIndex1.claim.createdAt   iso date timestamp of claim creation
+ * @apiSuccess (Claims) {Date}      result.ArrayIndex1.claim.updatedAt   iso date timestamp of claim update
+
+ * 
+ * 
+ * @apiErrorExample {text} Error-Response:
+ *     HTTP/1.1 500 Internal Server Error
+ *     Sorry, Could not update the claims right now
+ * */
 route.get('/claims/:id/update', auth.adminOnly, (req, res) => {
-  //TODO: For authorised requests only
   du.updateClaim(req.params.id, req.query)
-    .then(result => {
+    .then((result) => {
       res.send({ result: result })
     })
-    .catch(err => {
+    .catch((err) => {
       console.log(err)
       res.status(500).send('Sorry. Could not update the claim right now.')
     })
 })
 
-route.post('/claims/add', auth.ensureLoggedInGithub, (req, res) => {
+/**
+ * @api  {get} api/claims/add To add a new claim
+ * @apiVersion 0.0.3
+ * @apiGroup Claims
+ * @apiName Add New Claim
+ * @apiPermission github
+ * @apiDescription This endpoint is used to add new claims for bounties from the participant dashboard.
+ *
+ * @apiParam {String} issue_url         id of the claim to be updated.
+ * @apiParam {String} pull_url          new bounty of the claim
+ * @apiParam {Number} bounty            to update the claim
+ *
+ * @apiSuccess (Claims) {Object} claim containing details of newly created claim
+ * @apiSuccess (Claims) {number}    claim.id          unique id of the claim
+ * @apiSuccess (Claims) {String}    claim.user        username of the participant who made the claim
+ * @apiSuccess (Claims) {String}    claim.issueUrl    link of the issue submitted for claim
+ * @apiSuccess (Claims) {String}    claim.pullUrl     link of the pull request submitted for claim
+ * @apiSuccess (Claims) {String}    claim.repo        repository to which claim was made
+ * @apiSuccess (Claims) {String}    claim.reason      reason for current status of claim
+ * @apiSuccess (Claims) {Number}    claim.bounty      bounty to be awarded upon success
+ * @apiSuccess (Claims) {String}    claim.status      current status of claim
+ * @apiSuccess (Claims) {Date}      claim.createdAt     iso date timestamp of claim creation
+ * @apiSuccess (Claims) {Date}      claim.updatedAt     iso date timestamp of claim update
+ *
+ * @apiErrorExample {text} Error-Response:
+ *     HTTP/1.1 500 Internal Server Error
+ *     Sorry, Could not addd the claims right now
+ * */
+route.post('/claims/add', (req, res) => {
   if (process.env.BOSS_DEV === 'localhost') {
     req.user = {
       usergithub: {
@@ -64,7 +186,7 @@ route.post('/claims/add', auth.ensureLoggedInGithub, (req, res) => {
     return res.send("Sorry. Boss has ended, can't add claim from now.")
   }
   if (Date.now() < BOSS_START_DATE.getTime()) {
-    return res.send("Sorry. BOSS has not yet started")
+    return res.send('Sorry. BOSS has not yet started')
   }
 
   du.createClaim(
@@ -74,10 +196,10 @@ route.post('/claims/add', auth.ensureLoggedInGithub, (req, res) => {
     req.body.bounty,
     config.CLAIM_STATUS.CLAIMED
   )
-    .then(claim => {
+    .then((claim) => {
       res.send(claim)
     })
-    .catch(err => {
+    .catch((err) => {
       console.log(err)
       res.send('Sorry. Could not add the claim right now.')
     })