From f27706cb4bd6b5ee28b62c8f0566b8ab2b43985d Mon Sep 17 00:00:00 2001 From: Atte Kortesmaa Date: Tue, 6 Jun 2017 21:48:11 +0300 Subject: [PATCH] Improved API documentation for hall #8087 (#8536) * Improved API documentation for hall * Fixes typos, removes apiHeader definitions and curl example * Fixes @apiParam and capitalization errors. Moves @apiDefines to website/server/api-doc.js --- website/server/api-doc.js | 56 +++++++++++ website/server/controllers/api-v3/hall.js | 116 +++++++++++++++++++--- 2 files changed, 156 insertions(+), 16 deletions(-) diff --git a/website/server/api-doc.js b/website/server/api-doc.js index cc798c26db..14d136ef30 100644 --- a/website/server/api-doc.js +++ b/website/server/api-doc.js @@ -13,3 +13,59 @@ /** * @apiDefine Query Query Parameters */ + +/** + * @apiDefine Admin Moderators + * Contributors of tier 8 or higher can use this route. + */ + +/** + * @apiDefine NoAuthHeaders Missing authentication headers + * + * @apiError (401) {NotAuthorized} NoAuthHeaders Missing authentication headers + * + * @apiErrorExample Missing authentication headers + * { + * "success": false, + * "error": "NotAuthorized", + * "message": "Missing authentication headers." + * } + */ + +/** +* @apiDefine NoAccount There is no account that uses those credentials. +* +* @apiError (401) {NotAuthorized} NoAccount There is no account that uses those credentials +* +* @apiErrorExample No account +* { +* "success": false, +* "error": "NotAuthorized", +* "message": "There is no account that uses those credentials." +* } +*/ + +/** + * @apiDefine NotAdmin You don't have admin access. + * + * @apiError (401) {NotAuthorized} NotAdmin User is not an admin + * + * @apiErrorExample No admin access + * { + * "success": false, + * "error": "NotAuthorized", + * "message": "You don't have admin access." + * } + */ + +/** + * @apiDefine NoUser No user + * @apiError (404) {NotFound} NoUser The specified user could not be found. + * + * @apiErrorExample No user + * { + * "success": false, + * "error": "NotFound", + * "message": "User with id \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" not found." + * } + */ diff --git a/website/server/controllers/api-v3/hall.js b/website/server/controllers/api-v3/hall.js index a42bb6280f..026768d44e 100644 --- a/website/server/controllers/api-v3/hall.js +++ b/website/server/controllers/api-v3/hall.js @@ -6,22 +6,56 @@ import { } from '../../libs/errors'; import _ from 'lodash'; -/** - * @apiDefine Admin Moderators - * Contributors of tier 8 or higher can use this route. - */ - let api = {}; /** * @api {get} /api/v3/hall/patrons Get all patrons - * @apiDescription Only the first 50 patrons are returned. More can be accessed passing ?page=n + * @apiDescription Returns an array of objects containing the patrons who backed Habitica's + * original kickstarter. The array is sorted by the backer tier in descending order. + * By default, only the first 50 patrons are returned. More can be accessed by passing ?page=n * @apiName GetPatrons * @apiGroup Hall * - * @apiParam {Number} page Query Parameter - The result page. Default is 0 - * + * @apiParam (Query) {Number} [page=0] The result page. * @apiSuccess {Array} data An array of patrons + * + * @apiSuccessExample {json} Example response + * { + * "success": true, + * "data": [ + * { + * "_id": "3adb52a9-0dfb-4752-81f2-a62d911d1bf5", + * "profile": { + * "name": "mattboch" + * }, + * "contributor": {}, + * "backer": { + * "tier": 800, + * "npc": "Beast Master" + * } + * }, + * { + * "_id": "9da65443-ed43-4c21-804f-d260c1361596", + * "profile": { + * "name": "ʎǝlᴉɐq s,┴I" + * }, + * "contributor": { + * "text": "Pollen Purveyor", + * "admin": true, + * "level": 8 + * }, + * "backer": { + * "npc": "Town Crier", + * "tier": 800, + * "tokensApplied": true + * } + * } + * ] + * } + * + * + * @apiUse NoAuthHeaders + * @apiUse NoAccount */ api.getPatrons = { method: 'GET', @@ -56,7 +90,32 @@ api.getPatrons = { * @apiName GetHeroes * @apiGroup Hall * - * @apiSuccess {Array} data An array of heroes + * @apiDescription Returns an array of objects containing the heroes who have + * contributed for Habitica. The array is sorted by the contribution level in descending order. + * + * @apiSuccess {Array} heroes An array of heroes + * + * @apiSuccessExample {json} Example response: + * { + * "success": true, + * "data": [ + * { + * "_id": "e6e01d2a-c2fa-4b9f-9c0f-7865b777e7b5", + * "profile": { + * "name": "test2" + * }, + * "contributor": { + * "admin": false, + * "level": 2, + * "text": "Linguist" + * }, + * "backer": {} + * } + * ] + * } + * + * @apiUse NoAuthHeaders + * @apiUse NoAccount */ api.getHeroes = { method: 'GET', @@ -83,14 +142,19 @@ const heroAdminFields = 'contributor balance profile.name purchased items auth f /** * @api {get} /api/v3/hall/heroes/:heroId Get any user ("hero") given the UUID + * @apiParam {UUID} heroId user ID * @apiName GetHero * @apiGroup Hall + * @apiPermission Admin + * + * @apiDescription Returns the profile of the given user * * @apiSuccess {Object} data The user object * - * @apiPermission Admin - * - * @apiUse UserNotFound + * @apiUse NoAuthHeaders + * @apiUse NoAccount + * @apiUse NoUser + * @apiUse NotAdmin */ api.getHero = { method: 'GET', @@ -123,15 +187,35 @@ const gemsPerTier = {1: 3, 2: 3, 3: 3, 4: 4, 5: 4, 6: 4, 7: 4, 8: 0, 9: 0}; /** * @api {put} /api/v3/hall/heroes/:heroId Update any user ("hero") - * @apiDescription Must be an admin to make this request. + * @apiParam {UUID} heroId user ID * @apiName UpdateHero * @apiGroup Hall + * @apiPermission Admin + * + * @apiDescription Update user's gem balance, contributions & contribution tier and admin status. Grant items, block / unblock user's account and revoke / unrevoke chat privileges. + * + * @apiExample Example Body: + * { + * "balance": 1000, + * "auth": {"blocked": false}, + * "flags": {"chatRevoked": true}, + * "purchased": {"ads": true}, + * "contributor": { + * "admin": true, + * "contributions": "Improving API documentation", + * "level": 5, + * "text": "Scribe, Blacksmith" + * }, + * "itemPath": "items.pets.BearCub-Skeleton", + * "itemVal": 1 + * } * * @apiSuccess {Object} data The updated user object * - * @apiPermission Admin - * - * @apiUse UserNotFound + * @apiUse NoAuthHeaders + * @apiUse NoAccount + * @apiUse NoUser + * @apiUse NotAdmin */ api.updateHero = { method: 'PUT',