From 4990beccafd94e2a6e89152738abe4b2efdd4d6a Mon Sep 17 00:00:00 2001 From: Yash Kumar Verma Date: Mon, 18 May 2020 19:24:18 +0530 Subject: [PATCH] Documenting API and integrating apidocs :Fixes #239 --- .gitignore | 5 +- apidoc.json | 8 +++ package-lock.json | 5 ++ package.json | 6 +- routes/api.js | 146 ++++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 155 insertions(+), 15 deletions(-) create mode 100644 apidoc.json diff --git a/.gitignore b/.gitignore index 89cca88..22ac87f 100644 --- a/.gitignore +++ b/.gitignore @@ -55,4 +55,7 @@ audit/*.json # Semantic UI /semantic/* !/semantic/src/site -!/semantic/src/theme.config \ No newline at end of file +!/semantic/src/theme.config + +#docs +docs diff --git a/apidoc.json b/apidoc.json new file mode 100644 index 0000000..46f1986 --- /dev/null +++ b/apidoc.json @@ -0,0 +1,8 @@ +{ + "name": "Coding Blocks BOSS API", + "version": "0.0.3", + "description": "API powering BOSS Portal operations", + "template": { + "forceLanguage": "en" + } +} diff --git a/package-lock.json b/package-lock.json index 94d78db..7ff1506 100644 --- a/package-lock.json +++ b/package-lock.json @@ -209,6 +209,11 @@ "normalize-path": "^2.1.1" } }, + "apidocs": { + "version": "2017.3.9", + "resolved": "https://registry.npmjs.org/apidocs/-/apidocs-2017.3.9.tgz", + "integrity": "sha1-5BfUboCi2MSs68rfxIe4LA7xjCI=" + }, "append-buffer": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/append-buffer/-/append-buffer-1.0.2.tgz", diff --git a/package.json b/package.json index 0c80c9e..30e9637 100644 --- a/package.json +++ b/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", diff --git a/routes/api.js b/routes/api.js index 6e0ddbb..63316cd 100644 --- a/routes/api.js +++ b/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.') })