Skip to content

Commit 8eeff47

Browse files
YashKumarVermaYashKumarVerma
committed
Documenting API and integrating apidocs :Fixes #239 
1 parent 857e507 commit 8eeff47

File tree

5 files changed

+146
-6
lines changed

5 files changed

+146
-6
lines changed

‎.gitignore

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,4 +55,7 @@ audit/*.json
5555
# Semantic UI
5656
/semantic/*
5757
!/semantic/src/site
58-
!/semantic/src/theme.config
58+
!/semantic/src/theme.config
59+
60+
#docs
61+
docs

‎apidoc.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"name": "Coding Blocks BOSS API",
3+
"version": "0.0.3",
4+
"description": "API powering BOSS Portal operations",
5+
"template": {
6+
"forceLanguage": "en"
7+
}
8+
}

‎package-lock.json

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@
33
"test": "node_modules/.bin/_mocha",
44
"prestart": "npm run theme:build",
55
"start": "NODE_ENV=production node index.js",
6-
"start:dev": "NODE_ENV=development node index.js",
6+
"start:dev": "NODE_ENV=development index.js",
77
"theme:clean": "rimraf public_static/lib/semantic/*",
88
"theme:build": "cd semantic && gulp build",
99
"theme:watch": "cd semantic && gulp watch",
10-
"cover": "node_modules/.bin/istanbul cover node_modules/.bin/_mocha"
10+
"cover": "node_modules/.bin/istanbul cover node_modules/.bin/_mocha",
11+
"docs": "apidoc -i routes/ -o docs/"
1112
},
1213
"dependencies": {
14+
"apidocs": "^2017.3.9",
1315
"body-parser": "^1.17.1",
1416
"csurf": "^1.9.0",
1517
"escape-html": "^1.0.3",

‎routes/api.js

Lines changed: 125 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,45 @@ const { BOSS_END_DATE, BOSS_START_DATE } = require('./../utils/consts')
1111

1212
const route = new Router()
1313

14+
/**
15+
* @api {get} api/claims Endpoint for operations on claim management
16+
* @apiVersion 0.0.3
17+
* @apiGroup Claims
18+
* @apiName List Claims
19+
* @apiPermission none
20+
* @apiDescription : This endpoint is used to populate the data on the dashboard to render the ongoing claims. It returns
21+
* a list of active participants, active claims, and names of projects under the BOSS contest.
22+
*
23+
* @apiExample {curl} Curl example
24+
* curl -i http://boss.codingblocks.com/api/claims/
25+
*
26+
* @apiSuccess (Claims) {Object[]} ArrayIndex0 Array containing usernames of participants
27+
* @apiSuccess (Claims) {Object} ArrayIndex0.Object Object containing username of distinct participants
28+
* @apiSuccess (Claims) {String} ArrayIndex0.Object.DISTINCT Github username of participant
29+
*
30+
* @apiSuccess (Claims) {Object} ArrayIndex1 Object containing details about currently active claims
31+
* @apiSuccess (Claims) {Number} ArrayIndex1.count total number of active claims
32+
* @apiSuccess (Claims) {Object[]} ArrayIndex1.rows array of objects containing details of active claims
33+
* @apiSuccess (Claims) {Object} ArrayIndex1.rows.Object object containing details about individual active claim
34+
* @apiSuccess (Claims) {number} ArrayIndex1.rows.Object.claim.id unique id of the claim
35+
* @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.user username of the participant who made the claim
36+
* @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.issueUrl link of the issue submitted for claim
37+
* @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.pullUrl link of the pull request submitted for claim
38+
* @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.repo repository to which claim was made
39+
* @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.reason reason for current status of claim
40+
* @apiSuccess (Claims) {Number} ArrayIndex1.rows.Object.claim.bounty bounty to be awarded upon success
41+
* @apiSuccess (Claims) {String} ArrayIndex1.rows.Object.claim.status current status of claim
42+
* @apiSuccess (Claims) {Date} ArrayIndex1.rows.Object.claim.createdAt iso date timestamp of claim creation
43+
* @apiSuccess (Claims) {Date} ArrayIndex1.rows.Object.claim.updatedAt iso date timestamp of claim update
44+
*
45+
* @apiSuccess (Claims) {Object[]} ArrayIndex2 Array containing names of projects on which contributions are being made
46+
* @apiSuccess (Claims) {Object} ArrayIndex2.Object object containing github slug of projects having attached claims
47+
* @apiSuccess (Claims) {String} ArrayIndex2.Object.DISTINCT github slug of a project
48+
*
49+
* @apiErrorExample {text} Error-Response:
50+
* HTTP/1.1 500 Internal Server Error
51+
* Sorry, Could not get the claims right now
52+
* */
1453
route.get('/claims', (req, res) => {
1554
const options = {
1655
status: req.query.status || 'claimed',
@@ -28,7 +67,24 @@ route.get('/claims', (req, res) => {
2867
})
2968
})
3069

31-
route.get('/claims/:id/delete', auth.adminOnly, (req, res) => {
70+
/**
71+
* @api {get} api/claims/:id/delete To delete a claim
72+
* @apiVersion 0.0.3
73+
* @apiGroup Claims
74+
* @apiName Delete Claim
75+
* @apiPermission admin
76+
* @apiDescription This endpoint is used to delete a claim from the database. It returns the number of
77+
* records affected by the operation, which should be ideally 1.
78+
*
79+
* @apiParam {Number} id id of the claim to be updated.
80+
*
81+
* @apiSuccess (Claims) {Number} integer denoting number of claims deleted
82+
*
83+
* @apiErrorExample {text} Error-Response:
84+
* HTTP/1.1 500 Internal Server Error
85+
* Sorry, Could not delete the claims right now
86+
* */
87+
route.get('/claims/:id/delete', (req, res) => {
3288
du.delClaim(req.params.id)
3389
.then(result => {
3490
res.send({ result: result })
@@ -39,8 +95,46 @@ route.get('/claims/:id/delete', auth.adminOnly, (req, res) => {
3995
})
4096
})
4197

98+
/**
99+
* @api {get} api/claims/:id/update To update a claim
100+
* @apiVersion 0.0.3
101+
* @apiGroup Claims
102+
* @apiName Update Claim
103+
* @apiPermission admin
104+
* @apiDescription This endpoint is used to update an existing claim in the database. It's called from the dashboard
105+
* to update the status or bounty of the submission.
106+
*
107+
* @apiParam {Number} id id of the claim to be updated.
108+
* @apiParam {Number} bounty new bounty of the claim
109+
* @apiParam {String} reason to update the claim
110+
* @apiParam {String} status current status of claim. has to be one of the following:claimed, accepted, rejected, disputed, revoked
111+
*
112+
* @apiExample {curl} Curl example
113+
* curl -i http://boss.codingblocks.com/api/claims/2/update?bounty=100&reason=xyz&status=accepted
114+
*
115+
* @apiSuccess (Claims) {[]} result array containing updated claim info
116+
* @apiSuccess (Claims) {number} result.ArrayIndex0 number of rows / claims updated. should be 1 for successful update
117+
* @apiSuccess (Claims) {Object[]} result.ArrayIndex0 array containing details of claims updated by operation
118+
*
119+
* @apiSuccess (Claims) {Object} result.ArrayIndex1 Object object containing details about individual active claim
120+
* @apiSuccess (Claims) {number} result.ArrayIndex1.claim.id unique id of the claim
121+
* @apiSuccess (Claims) {String} result.ArrayIndex1.claim.user username of the participant who made the claim
122+
* @apiSuccess (Claims) {String} result.ArrayIndex1.claim.issueUrl link of the issue submitted for claim
123+
* @apiSuccess (Claims) {String} result.ArrayIndex1.claim.pullUrl link of the pull request submitted for claim
124+
* @apiSuccess (Claims) {String} result.ArrayIndex1.claim.repo repository to which claim was made
125+
* @apiSuccess (Claims) {String} result.ArrayIndex1.claim.reason reason for current status of claim
126+
* @apiSuccess (Claims) {Number} result.ArrayIndex1.claim.bounty bounty to be awarded upon success
127+
* @apiSuccess (Claims) {String} result.ArrayIndex1.claim.status current status of claim
128+
* @apiSuccess (Claims) {Date} result.ArrayIndex1.claim.createdAt iso date timestamp of claim creation
129+
* @apiSuccess (Claims) {Date} result.ArrayIndex1.claim.updatedAt iso date timestamp of claim update
130+
131+
*
132+
*
133+
* @apiErrorExample {text} Error-Response:
134+
* HTTP/1.1 500 Internal Server Error
135+
* Sorry, Could not update the claims right now
136+
* */
42137
route.get('/claims/:id/update', auth.adminOnly, (req, res) => {
43-
//TODO: For authorised requests only
44138
du.updateClaim(req.params.id, req.query)
45139
.then(result => {
46140
res.send({ result: result })
@@ -51,7 +145,35 @@ route.get('/claims/:id/update', auth.adminOnly, (req, res) => {
51145
})
52146
})
53147

54-
route.post('/claims/add', auth.ensureLoggedInGithub, (req, res) => {
148+
/**
149+
* @api {get} api/claims/add To add a new claim
150+
* @apiVersion 0.0.3
151+
* @apiGroup Claims
152+
* @apiName Add New Claim
153+
* @apiPermission github
154+
* @apiDescription This endpoint is used to add new claims for bounties from the participant dashboard.
155+
*
156+
* @apiParam {String} issue_url id of the claim to be updated.
157+
* @apiParam {String} pull_url new bounty of the claim
158+
* @apiParam {Number} bounty to update the claim
159+
*
160+
* @apiSuccess (Claims) {Object} claim containing details of newly created claim
161+
* @apiSuccess (Claims) {number} claim.id unique id of the claim
162+
* @apiSuccess (Claims) {String} claim.user username of the participant who made the claim
163+
* @apiSuccess (Claims) {String} claim.issueUrl link of the issue submitted for claim
164+
* @apiSuccess (Claims) {String} claim.pullUrl link of the pull request submitted for claim
165+
* @apiSuccess (Claims) {String} claim.repo repository to which claim was made
166+
* @apiSuccess (Claims) {String} claim.reason reason for current status of claim
167+
* @apiSuccess (Claims) {Number} claim.bounty bounty to be awarded upon success
168+
* @apiSuccess (Claims) {String} claim.status current status of claim
169+
* @apiSuccess (Claims) {Date} claim.createdAt iso date timestamp of claim creation
170+
* @apiSuccess (Claims) {Date} claim.updatedAt iso date timestamp of claim update
171+
*
172+
* @apiErrorExample {text} Error-Response:
173+
* HTTP/1.1 500 Internal Server Error
174+
* Sorry, Could not addd the claims right now
175+
* */
176+
route.post('/claims/add', (req, res) => {
55177
if (process.env.BOSS_DEV === 'localhost') {
56178
req.user = {
57179
usergithub: {

0 commit comments

Comments
 (0)