krikkert/habitica
1
0
Fork 0
mirror of https://github.com/HabitRPG/habitica.git synced 2025-12-19 15:48:04 +01:00
Code Issues Packages Projects Releases Wiki Activity

v3: improve docs and fix bugs

Browse Source
This commit is contained in:
Matteo Pagliazzi
2016-04-22 12:15:24 +02:00
parent 6568fcfd5e
commit 1fe2220aa1
3 changed files with 140 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
common/script/ops/rebirth.js
View File

@@ -102,7 +102,7 @@ module.exports = function rebirth (user, tasks = [], req = {}, analytics) {
return user; return user;
} else { } else {
return [ return [
user, {user, tasks},
i18n.t('rebirthComplete'), i18n.t('rebirthComplete'),
]; ];
} }

2
website/src/controllers/api-v3/auth.js
View File

@@ -380,7 +380,7 @@ api.updatePassword = {
* *
* @apiParam {string} email Body parameter - The email address of the user * @apiParam {string} email Body parameter - The email address of the user
* *
* @apiSuccess {string} data.message The localized success message * @apiSuccess {string} message The localized success message
**/ **/
api.resetPassword = { api.resetPassword = {
method: 'POST', method: 'POST',

212
website/src/controllers/api-v3/user.js
View File

@@ -422,7 +422,7 @@ api.castSpell = {
* @apiName UserSleep * @apiName UserSleep
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data Will return an object with the new `user.preferences.sleep` value. Example `{preferences: {sleep: true}}` * @apiSuccess {boolean} data user.preferences.sleep
*/ */
api.sleep = { api.sleep = {
method: 'POST', method: 'POST',
@@ -442,7 +442,9 @@ api.sleep = {
* @apiName UserAllocate * @apiName UserAllocate
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} Returs `user.stats` * @apiParam {string} stat Query parameter - Defaults to 'str', mast be one of be of str, con, int or per
*
* @apiSuccess {Object} data user.stats
*/ */
api.allocate = { api.allocate = {
method: 'POST', method: 'POST',
@@ -462,7 +464,7 @@ api.allocate = {
* @apiName UserAllocateNow * @apiName UserAllocateNow
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `stats` * @apiSuccess {Object} data user.stats
*/ */
api.allocateNow = { api.allocateNow = {
method: 'POST', method: 'POST',
@@ -478,14 +480,12 @@ api.allocateNow = {
/** /**
* @api {post} /user/buy/:key Buy gear, armoire or potion * @api {post} /user/buy/:key Buy gear, armoire or potion
* @apiDescription Under the hood uses UserBuyGear, UserBuyPotion and UserBuyArmoire
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserBuy * @apiName UserBuy
* @apiGroup User * @apiGroup User
* *
* @apiParam {string} key The item to buy. * @apiParam {string} key The item to buy.
*
* @apiSuccess {Object} data `items`
* @apiSuccess {string} message
*/ */
api.buy = { api.buy = {
method: 'POST', method: 'POST',
@@ -507,8 +507,11 @@ api.buy = {
* *
* @apiParam {string} key The item to buy. * @apiParam {string} key The item to buy.
* *
* @apiSuccess {Object} data `items` * @apiSuccess {object} data.items user.items
* @apiSuccess {string} message * @apiSuccess {object} data.flags user.flags
* @apiSuccess {object} data.achievements user.achievements
* @apiSuccess {object} data.stats user.stats
* @apiSuccess {string} message Success message
*/ */
api.buyGear = { api.buyGear = {
method: 'POST', method: 'POST',
@@ -530,9 +533,10 @@ api.buyGear = {
* *
* @apiParam {string} key The item to buy. * @apiParam {string} key The item to buy.
* *
* @apiSuccess {Object} data `items flags` * @apiSuccess {object} data.items user.items
* @apiSuccess {object} armoireResp Optional extra item given by the armoire * @apiSuccess {object} data.flags user.flags
* @apiSuccess {string} message * @apiSuccess {object} data.armoire Extra item given by the armoire
* @apiSuccess {string} message Success message
*/ */
api.buyArmoire = { api.buyArmoire = {
method: 'POST', method: 'POST',
@@ -554,8 +558,8 @@ api.buyArmoire = {
* *
* @apiParam {string} key The item to buy. * @apiParam {string} key The item to buy.
* *
* @apiSuccess {Object} data `stats` * @apiSuccess {Object} data user.stats
* @apiSuccess {string} message * @apiSuccess {string} message Success message
*/ */
api.buyPotion = { api.buyPotion = {
method: 'POST', method: 'POST',
@@ -577,8 +581,9 @@ api.buyPotion = {
* *
* @apiParam {string} key The mystery set to buy. * @apiParam {string} key The mystery set to buy.
* *
* @apiSuccess {Object} data `items, purchased.plan.consecutive` * @apiSuccess {Object} data.items user.items
* @apiSuccess {string} message * @apiSuccess {Object} data.purchasedPlanConsecutive user.purchased.plan.consecutive
* @apiSuccess {string} message Success message
*/ */
api.buyMysterySet = { api.buyMysterySet = {
method: 'POST', method: 'POST',
@@ -600,8 +605,8 @@ api.buyMysterySet = {
* *
* @apiParam {string} key The quest spell to buy. * @apiParam {string} key The quest spell to buy.
* *
* @apiSuccess {Object} data `items.quests` * @apiSuccess {Object} data `user.items.quests`
* @apiSuccess {string} message * @apiSuccess {string} message Success message
*/ */
api.buyQuest = { api.buyQuest = {
method: 'POST', method: 'POST',
@@ -623,8 +628,9 @@ api.buyQuest = {
* *
* @apiParam {string} key The special spell to buy. * @apiParam {string} key The special spell to buy.
* *
* @apiSuccess {Object} data `items, stats` * @apiSuccess {Object} data.stats user.stats
* @apiSuccess {string} message * @apiSuccess {Object} data.items user.items
* @apiSuccess {string} message Success message
*/ */
api.buySpecialSpell = { api.buySpecialSpell = {
method: 'POST', method: 'POST',
@@ -647,7 +653,7 @@ api.buySpecialSpell = {
* @apiParam {string} egg The egg to use. * @apiParam {string} egg The egg to use.
* @apiParam {string} hatchingPotion The hatching potion to use. * @apiParam {string} hatchingPotion The hatching potion to use.
* *
* @apiSuccess {Object} data `user.items` * @apiSuccess {Object} data user.items
* @apiSuccess {string} message * @apiSuccess {string} message
*/ */
api.hatch = { api.hatch = {
@@ -668,11 +674,11 @@ api.hatch = {
* @apiName UserEquip * @apiName UserEquip
* @apiGroup User * @apiGroup User
* *
* @apiParam {string} type * @apiParam {string} type The type of item to equip (mount, pet, costume or equipped)
* @apiParam {string} key * @apiParam {string} key The item to equip
* *
* @apiSuccess {Object} data `user.items` * @apiSuccess {Object} data user.items
* @apiSuccess {string} message Optional * @apiSuccess {string} message Optional success message
*/ */
api.equip = { api.equip = {
method: 'POST', method: 'POST',
@@ -695,8 +701,8 @@ api.equip = {
* @apiParam {string} pet * @apiParam {string} pet
* @apiParam {string} food * @apiParam {string} food
* *
* @apiSuccess {Object} data The fed pet * @apiSuccess {number} data The pet value
* @apiSuccess {string} message * @apiSuccess {string} message Success message
*/ */
api.feed = { api.feed = {
method: 'POST', method: 'POST',
@@ -712,13 +718,17 @@ api.feed = {
/** /**
* @api {post} /api/v3/user/change-class Change class. * @api {post} /api/v3/user/change-class Change class.
* @apiDescription User must be at least level 10. If ?class is defined and user.flags.classSelected is false it'll change the class. If user.preferences.disableClasses it'll enable classes, otherwise it sets user.flags.classSelected to false (costs 3 gems)
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserChangeClass * @apiName UserChangeClass
* @apiGroup User * @apiGroup User
* *
* @apiParam {string} class ?class={warrior|rogue|wizard|healer}. If missing will * @apiParam {string} class Query parameter - ?class={warrior|rogue|wizard|healer}.
* *
* @apiSuccess {Object} data `stats flags items preferences` * @apiSuccess {object} data.flags user.flags
* @apiSuccess {object} data.stats user.stats
* @apiSuccess {object} data.preferences user.preferences
* @apiSuccess {object} data.items user.items
*/ */
api.changeClass = { api.changeClass = {
method: 'POST', method: 'POST',
@@ -738,7 +748,9 @@ api.changeClass = {
* @apiName UserDisableClasses * @apiName UserDisableClasses
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `stats flags preferences` * @apiSuccess {object} data.flags user.flags
* @apiSuccess {object} data.stats user.stats
* @apiSuccess {object} data.preferences user.preferences
*/ */
api.disableClasses = { api.disableClasses = {
method: 'POST', method: 'POST',
@@ -758,10 +770,12 @@ api.disableClasses = {
* @apiName UserPurchase * @apiName UserPurchase
* @apiGroup User * @apiGroup User
* *
* @apiParam {string} type Type of item to purchase * @apiParam {string} type Type of item to purchase. Must be one of: gem, gems, eggs, hatchingPotions, food, quests or gear
* @apiParam {string} key Item's key * @apiParam {string} key Item's key
* *
* @apiSuccess {Object} data `items balance` * @apiSuccess {object} data.items user.items
* @apiSuccess {number} data.balance user.balance
* @apiSuccess {string} message Success message
*/ */
api.purchase = { api.purchase = {
method: 'POST', method: 'POST',
@@ -781,10 +795,12 @@ api.purchase = {
* @apiName UserPurchaseHourglass * @apiName UserPurchaseHourglass
* @apiGroup User * @apiGroup User
* *
* @apiParam {string} type {pets|mounts}. The type of item to purchase * @apiParam {string} type The type of item to purchase (pets or mounts)
* @apiParam {string} key Ex: {MantisShrimp-Base}. The key for the mount/pet * @apiParam {string} key Ex: {MantisShrimp-Base}. The key for the mount/pet
* *
* @apiSuccess {Object} data `items purchased.plan.consecutive` * @apiSuccess {object} data.items user.items
* @apiSuccess {object} data.purchasedPlanConsecutive user.purchased.plan.consecutive
* @apiSuccess {string} message Success message
*/ */
api.userPurchaseHourglass = { api.userPurchaseHourglass = {
method: 'POST', method: 'POST',
@@ -806,7 +822,9 @@ api.userPurchaseHourglass = {
* *
* @apiParam {string} cardType Type of card to read * @apiParam {string} cardType Type of card to read
* *
* @apiSuccess {Object} data `items.special flags.cardReceived` * @apiSuccess {object} data.specialItems user.items.special
* @apiSuccess {boolean} data.cardReceived user.flags.cardReceived
* @apiSuccess {string} message Success message
*/ */
api.readCard = { api.readCard = {
method: 'POST', method: 'POST',
@@ -826,7 +844,8 @@ api.readCard = {
* @apiName UserOpenMysteryItem * @apiName UserOpenMysteryItem
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `user.items.gear.owned` * @apiSuccess {Object} data user.items.gear.owned
* @apiSuccess {string} message Success message
*/ */
api.userOpenMysteryItem = { api.userOpenMysteryItem = {
method: 'POST', method: 'POST',
@@ -840,13 +859,17 @@ api.userOpenMysteryItem = {
}, },
}; };
/** /*
* @api {post} /api/v3/user/webhook * @api {post} /api/v3/user/webhook
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserAddWebhook * @apiName UserAddWebhook
* @apiGroup User * @apiGroup User
* @apiSuccess {Object} webhook The created webhook *
**/ * @apiParam {string} url Body parameter - The webhook's urò
* @apiParam {boolean} enabled Body parameter - If the webhook should be enabled
*
* @apiSuccess {Object} data The created webhook
*/
api.addWebhook = { api.addWebhook = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -859,13 +882,18 @@ api.addWebhook = {
}, },
}; };
/** /*
* @api {put} /api/v3/user/webhook/:id * @api {put} /api/v3/user/webhook/:id
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserUpdateWebhook * @apiName UserUpdateWebhook
* @apiGroup User * @apiGroup User
* @apiSuccess {Object} webhook The updated webhook *
**/ * @apiParam {UUID} id The id of the webhook to update
* @apiParam {string} url Body parameter - The webhook's urò
* @apiParam {boolean} enabled Body parameter - If the webhook should be enabled
*
* @apiSuccess {Object} data The updated webhook
*/
api.updateWebhook = { api.updateWebhook = {
method: 'PUT', method: 'PUT',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -878,13 +906,16 @@ api.updateWebhook = {
}, },
}; };
/** /*
* @api {delete} /api/v3/user/webhook/:id * @api {delete} /api/v3/user/webhook/:id
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserDeleteWebhook * @apiName UserDeleteWebhook
* @apiGroup User * @apiGroup User
* @apiSuccess {Object} webhooks The user webhooks *
**/ * @apiParam {UUID} id The id of the webhook to delete
*
* @apiSuccess {Object} data The user webhooks
*/
api.deleteWebhook = { api.deleteWebhook = {
method: 'DELETE', method: 'DELETE',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -903,7 +934,8 @@ api.deleteWebhook = {
* @apiName UserReleasePets * @apiName UserReleasePets
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `user.items.pets` * @apiSuccess {Object} data.items `user.items.pets`
* @apiSuccess {string} message Success message
*/ */
api.userReleasePets = { api.userReleasePets = {
method: 'POST', method: 'POST',
@@ -922,8 +954,11 @@ api.userReleasePets = {
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserReleaseBoth * @apiName UserReleaseBoth
* @apiGroup User * @apiGroup User
*
* @apiSuccess {Object} data `user.items.gear.owned` * @apiSuccess {Object} data.achievements
* @apiSuccess {Object} data.items
* @apiSuccess {number} data.balance
* @apiSuccess {string} message Success message
*/ */
api.userReleaseBoth = { api.userReleaseBoth = {
method: 'POST', method: 'POST',
@@ -943,7 +978,8 @@ api.userReleaseBoth = {
* @apiName UserReleaseMounts * @apiName UserReleaseMounts
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `mounts` * @apiSuccess {Object} data user.items.mounts
* @apiSuccess {string} message Success message
*/ */
api.userReleaseMounts = { api.userReleaseMounts = {
method: 'POST', method: 'POST',
@@ -958,12 +994,17 @@ api.userReleaseMounts = {
}; };
/* /*
* @api {post} /api/v3/user/sell/:type/:key Sells user's items. * @api {post} /api/v3/user/sell/:type/:key Sells a gold item owned by the user.
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName UserSell * @apiName UserSell
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `stats items` * @apiParam {string} type The type of item to sell. Acceptable types are eggs, hatchingPotions, food
* @apiParam {string} key The key of the item
*
* @apiSuccess {Object} data.stats
* @apiSuccess {Object} data.items
* @apiSuccess {string} message Success message
*/ */
api.userSell = { api.userSell = {
method: 'POST', method: 'POST',
@@ -983,7 +1024,12 @@ api.userSell = {
* @apiName UserUnlock * @apiName UserUnlock
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `purchased preferences items` * @apiParam {string} path Query parameter. The path to unlock
*
* @apiSuccess {Object} data.purchased
* @apiSuccess {Object} data.items`
* @apiSuccess {Object} data.preferences`
* @apiSuccess {string} message`
*/ */
api.userUnlock = { api.userUnlock = {
method: 'POST', method: 'POST',
@@ -1003,7 +1049,8 @@ api.userUnlock = {
* @apiName UserRevive * @apiName UserRevive
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `user.items` * @apiSuccess {Object} data user.items
* @apiSuccess {string} message Success message
*/ */
api.userRevive = { api.userRevive = {
method: 'POST', method: 'POST',
@@ -1023,7 +1070,9 @@ api.userRevive = {
* @apiName UserRebirth * @apiName UserRebirth
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `user` * @apiSuccess {Object} data.userr
* @apiSuccess {array} data.tasks User's modified tasks (no rewards)
* @apiSuccess {string} message Success message
*/ */
api.userRebirth = { api.userRebirth = {
method: 'POST', method: 'POST',
@@ -1047,11 +1096,14 @@ api.userRebirth = {
}; };
/** /**
* @api {post} /api/v3/user/block/:uuid blocks and unblocks a user * @api {post} /api/v3/user/block/:uuid Blocks and unblocks a user
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName BlockUser * @apiName BlockUser
* @apiGroup User * @apiGroup User
* @apiSuccess user.inbox.blocks *
* @apiParam {UUID} uuid The uuid of the user to block / unblock
*
* @apiSuccess {array} data user.inbox.blocks
**/ **/
api.blockUser = { api.blockUser = {
method: 'POST', method: 'POST',
@@ -1066,11 +1118,14 @@ api.blockUser = {
}; };
/** /**
* @api {delete} /api/v3/user/messages/:id delete this message * @api {delete} /api/v3/user/messages/:id Delete a message
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName deleteMessage * @apiName deleteMessage
* @apiGroup User * @apiGroup User
* @apiSuccess user.inbox.messages *
* @apiParam {UUID} id The id of the message to delete
*
* @apiSuccess {object} data user.inbox.messages
**/ **/
api.deleteMessage = { api.deleteMessage = {
method: 'DELETE', method: 'DELETE',
@@ -1085,11 +1140,12 @@ api.deleteMessage = {
}; };
/** /**
* @api {delete} /api/v3/user/messages delete all messages * @api {delete} /api/v3/user/messages Delete all messages
* @apiVersion 3.0.0 * @apiVersion 3.0.0
* @apiName clearMessages * @apiName clearMessages
* @apiGroup User * @apiGroup User
* @apiSuccess user.inbox.messages *
* @apiSuccess {object} data user.inbox.messages
**/ **/
api.clearMessages = { api.clearMessages = {
method: 'DELETE', method: 'DELETE',
@@ -1109,7 +1165,9 @@ api.clearMessages = {
* @apiName UserReroll * @apiName UserReroll
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `user` * @apiSuccess {Object} data.user
* @apiSuccess {Object} data.tasks User's modified tasks (no rewards)
* @apiSuccess {Object} message Success message
*/ */
api.userReroll = { api.userReroll = {
method: 'POST', method: 'POST',
@@ -1139,7 +1197,11 @@ api.userReroll = {
* @apiName UserAddPushDevice * @apiName UserAddPushDevice
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `pushDevices` * @apiParam {string} regId The id of the push device
* @apiParam {string} uuid The type of push device
*
* @apiSuccess {Object} data List of push devices
* @apiSuccess {string} message Success message
*/ */
api.userAddPushDevice = { api.userAddPushDevice = {
method: 'POST', method: 'POST',
@@ -1161,7 +1223,9 @@ api.userAddPushDevice = {
* @apiName UserReset * @apiName UserReset
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data `user` * @apiSuccess {Object} data.user
* @apiSuccess {Object} data.tasksToRemove IDs of removed tasks
* @apiSuccess {string} message Success message
*/ */
api.userReset = { api.userReset = {
method: 'POST', method: 'POST',