From 1eb351607effdb586c896c0f2dc931380dc9ae8a Mon Sep 17 00:00:00 2001 From: Yash Kumar Verma Date: Mon, 18 May 2020 19:30:02 +0530 Subject: [PATCH] Documenting API and integrating apidocs :Fixes #239 --- .gitignore | 3 ++ apidoc.json | 8 +++ package-lock.json | 5 ++ package.json | 4 +- routes/api.js | 128 ++++++++++++++++++++++++++++++++++++++++++++-- 5 files changed, 144 insertions(+), 4 deletions(-) create mode 100644 apidoc.json diff --git a/.gitignore b/.gitignore index 89cca88..95da814 100644 --- a/.gitignore +++ b/.gitignore @@ -49,6 +49,9 @@ fabric.properties secrets.json audit/*.json +#docs +docs + # IDE /.vscode/ 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..0ccc639 100644 --- a/package.json +++ b/package.json @@ -1,15 +1,17 @@ { "scripts": { "test": "node_modules/.bin/_mocha", + "docs": "apidoc -i routes/ -o docs/", "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 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" }, "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..4e6ee20 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', @@ -28,7 +67,24 @@ route.get('/claims', (req, res) => { }) }) -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 => { res.send({ result: result }) @@ -39,8 +95,46 @@ route.get('/claims/:id/delete', auth.adminOnly, (req, res) => { }) }) +/** + * @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 => { res.send({ result: result }) @@ -51,7 +145,35 @@ route.get('/claims/:id/update', auth.adminOnly, (req, res) => { }) }) -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: {