diff --git a/.gitignore b/.gitignore index 21f3fde..fb4f5e9 100644 --- a/.gitignore +++ b/.gitignore @@ -50,6 +50,9 @@ secrets.json audit/*.json public_static/ +#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 f3e2066..a666a2a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -371,6 +371,18 @@ "resolved": "https://registry.npmjs.org/ansicolors/-/ansicolors-0.2.1.tgz", "integrity": "sha1-vgiVmQl7dKXJxKhKDNvNtivYeu8=" }, + "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", + "integrity": "sha1-2CIM9GYIFSXv6lBhTz3mUU36WPE=", + "requires": { + "buffer-equal": "^1.0.0" + } "ansistyles": { "version": "0.1.3", "resolved": "https://registry.npmjs.org/ansistyles/-/ansistyles-0.1.3.tgz", diff --git a/package.json b/package.json index 5b8a748..38073bd 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,7 @@ { "scripts": { "test": "node_modules/.bin/_mocha", + "docs": "apidoc -i routes/ -o docs/", "start": "cross-env NODE_ENV=production node index.js", "start:dev": "cross-env NODE_ENV=development node index.js", "cover": "node_modules/.bin/istanbul cover node_modules/.bin/_mocha", @@ -8,6 +9,7 @@ "probot:run": "probot run ./bot/index.js --private-key ./bot_key.pem" }, "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: {