chore(docs): Define resource not found errors and permissions

website/server/controllers/api-v3/challenges.js

@@ -20,12 +20,19 @@ import csvStringify from '../../libs/csvStringify';
 
 let api = {};
 
+/**
+ * @apiDefine ChallengeNotFound
+ * @apiError (404) {NotFound} ChallengeNotFound The specified challenge could not be found.
+ */
+
 /**
  * @api {post} /api/v3/challenges Create a new challenge
  * @apiName CreateChallenge
  * @apiGroup Challenge
  *
  * @apiSuccess {Object} data The newly created challenge
+ *
+ * @apiUse GroupNotFound
  */
 api.createChallenge = {
   method: 'POST',
@@ -116,6 +123,8 @@ api.createChallenge = {
  * @apiParam {UUID} challengeId The challenge _id
  *
  * @apiSuccess {Object} data The challenge the user joined
+ *
+ * @apiUse ChallengeNotFound
  */
 api.joinChallenge = {
   method: 'POST',
@@ -162,6 +171,8 @@ api.joinChallenge = {
  * @apiParam {UUID} challengeId The challenge _id
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse ChallengeNotFound
  */
 api.leaveChallenge = {
   method: 'POST',
@@ -244,6 +255,8 @@ api.getUserChallenges = {
  * @apiParam {UUID} groupId The group _id
  *
  * @apiSuccess {Array} data An array of challenges sorted with official challenges first, followed by the challenges in order from newest to oldest
+ *
+ * @apiUse GroupNotFound
  */
 api.getGroupChallenges = {
   method: 'GET',
@@ -286,6 +299,8 @@ api.getGroupChallenges = {
  * @apiParam {UUID} challengeId The challenge _id
  *
  * @apiSuccess {Object} data The challenge object
+ *
+ * @apiUse ChallengeNotFound
  */
 api.getChallenge = {
   method: 'GET',
@@ -328,6 +343,8 @@ api.getChallenge = {
  * @apiParam {UUID} challengeId The challenge _id
  *
  * @apiSuccess {String} challenge A csv file
+ *
+ * @apiUse ChallengeNotFound
  */
 api.exportChallengeCsv = {
   method: 'GET',
@@ -400,6 +417,8 @@ api.exportChallengeCsv = {
  * @apiParam {UUID} challengeId The challenge _id
  *
  * @apiSuccess {Object} data The updated challenge
+ *
+ * @apiUse ChallengeNotFound
  */
 api.updateChallenge = {
   method: 'PUT',
@@ -445,6 +464,8 @@ api.updateChallenge = {
  * @apiParam {UUID} challengeId The _id for the challenge to delete
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse ChallengeNotFound
  */
 api.deleteChallenge = {
   method: 'DELETE',
@@ -477,6 +498,8 @@ api.deleteChallenge = {
  * @apiParam {UUID} winnerId The _id of the winning user
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse ChallengeNotFound
  */
 api.selectChallengeWinner = {
   method: 'POST',

website/server/controllers/api-v3/chat.js

@@ -17,6 +17,11 @@ const FLAG_REPORT_EMAILS = nconf.get('FLAG_REPORT_EMAIL').split(',').map((email)
   return { email, canSend: true };
 });
 
+/**
+ * @apiDefine MessageNotFound
+ * @apiError (404) {NotFound} MessageNotFound The specified message could not be found.
+ */
+
 let api = {};
 
 async function getAuthorEmailFromMessage (message) {
@@ -43,6 +48,8 @@ async function getAuthorEmailFromMessage (message) {
  * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
  *
  * @apiSuccess {Array} data An array of chat messages
+ *
+ * @apiUse GroupNotFound
  */
 api.getChat = {
   method: 'GET',
@@ -73,6 +80,8 @@ api.getChat = {
  * @apiParam {UUID} previousMsg Query parameter - The previous chat message which will force a return of the full group chat
  *
  * @apiSuccess data An array of chat messages if a new message was posted after previousMsg, otherwise the posted message
+ *
+ * @apiUse GroupNotFound
  */
 api.postChat = {
   method: 'POST',
@@ -136,6 +145,9 @@ api.postChat = {
  * @apiParam {UUID} chatId The chat message _id
  *
  * @apiSuccess {Object} data The liked chat message
+ *
+ * @apiUse GroupNotFound
+ * @apiUse MessageNotFound
  */
 api.likeChat = {
   method: 'POST',
@@ -156,6 +168,7 @@ api.likeChat = {
 
     let message = _.find(group.chat, {id: req.params.chatId});
     if (!message) throw new NotFound(res.t('messageGroupChatNotFound'));
+    // TODO correct this error type
     if (message.uuid === user._id) throw new NotFound(res.t('messageGroupChatLikeOwnMessage'));
 
     let update = {$set: {}};
@@ -192,8 +205,8 @@ api.likeChat = {
  * @apiSuccess {UUID} data.uuid The user id of the author of the message
  * @apiSuccess {String} data.user The username of the author of the message
  *
- * @apiError GroupNotFound Group could not be found or you don't have access
- * @apiError ChatNotFound Chat message with specified id could not be found
+ * @apiUse GroupNotFound
+ * @apiUse MessageNotFound
  * @apiError FlagOwnMessage Chat messages cannot be flagged by the author of the message
  * @apiError AlreadyFlagged Chat messages cannot be flagged more than once by a user
  */
@@ -225,6 +238,7 @@ api.flagChat = {
 
     // Log user ids that have flagged the message
     if (!message.flags) message.flags = {};
+    // TODO fix error type
     if (message.flags[user._id] && !user.contributor.admin) throw new NotFound(res.t('messageGroupChatFlagAlreadyReported'));
     message.flags[user._id] = true;
     update.$set[`chat.$.flags.${user._id}`] = true;
@@ -282,7 +296,7 @@ api.flagChat = {
 /**
  * @api {post} /api/v3/groups/:groupId/chat/:chatId/clearflags Clear flags
  * @apiDescription Resets the flag count on a chat message. Retains the id of the user's that have flagged the message. (Only visible to moderators)
- * @apiPermission Moderators
+ * @apiPermission Admin
  * @apiName ClearFlags
  * @apiGroup Chat
  *
@@ -291,9 +305,9 @@ api.flagChat = {
  *
  * @apiSuccess {Object} data An empty object
  *
+ * @apiUse GroupNotFound
+ * @apiUse MessageNotFound
  * @apiError MustBeAdmin Must be a moderator to use this route
- * @apiError GroupNotFound Group could not be found or you don't have access
- * @apiError ChatNotFound Chat message with specified id could not be found
  */
 api.clearChatFlags = {
   method: 'Post',
@@ -404,6 +418,9 @@ api.seenChat = {
  *
  * @apiSuccess data The updated chat array or an empty object if no message was posted after previousMsg
  * @apiSuccess {Object} data An empty object when the previous message was deleted
+ *
+ * @apiUse GroupNotFound
+ * @apiUse MessageNotFound
  */
 api.deleteChat = {
   method: 'DELETE',

website/server/controllers/api-v3/debug.js

@@ -4,13 +4,23 @@ import { BadRequest } from '../../libs/errors';
 import { content } from '../../../common';
 import _ from 'lodash';
 
+/**
+ * @apiDefine Development Development
+ * These routes only exist while Habitica is in development mode. (Such as running a local instance on your computer)
+ */
+
+/**
+ * @apiDefine Developers Local Development
+ * This route only exists when developing Habitica in non-production environment.
+ */
+
 let api = {};
 
 /**
  * @api {post} /api/v3/debug/add-ten-gems Add ten gems to the current user
- * @apiDescription Only available in development mode.
  * @apiName AddTenGems
  * @apiGroup Development
+ * @apiPermission Developers
  *
  * @apiSuccess {Object} data An empty Object
  */
@@ -31,9 +41,9 @@ api.addTenGems = {
 
 /**
  * @api {post} /api/v3/debug/add-hourglass Add Hourglass to the current user
- * @apiDescription Only available in development mode.
  * @apiName AddHourglass
  * @apiGroup Development
+ * @apiPermission Developers
  *
  * @apiSuccess {Object} data An empty Object
  */
@@ -54,9 +64,9 @@ api.addHourglass = {
 
 /**
  * @api {post} /api/v3/debug/set-cron Set lastCron for user
- * @apiDescription Only available in development mode.
  * @apiName setCron
  * @apiGroup Development
+ * @apiPermission Developers
  *
  * @apiSuccess {Object} data An empty Object
  */
@@ -78,9 +88,9 @@ api.setCron = {
 
 /**
  * @api {post} /api/v3/debug/make-admin Sets contributor.admin to true
- * @apiDescription Only available in development mode.
  * @apiName setCron
  * @apiGroup Development
+ * @apiPermission Developers
  *
  * @apiSuccess {Object} data An empty Object
  */
@@ -101,9 +111,9 @@ api.makeAdmin = {
 
 /**
  * @api {post} /api/v3/debug/modify-inventory Manipulate user's inventory
- * @apiDescription Only available in development mode.
  * @apiName modifyInventory
  * @apiGroup Development
+ * @apiPermission Developers
  *
  * @apiSuccess {Object} data An empty Object
  */
@@ -141,9 +151,9 @@ api.modifyInventory = {
 
 /**
  * @api {post} /api/v3/debug/quest-progress Artificially accelerate quest progress
- * @apiDescription Only available in development mode.
  * @apiName questProgress
  * @apiGroup Development
+ * @apiPermission Developers
  *
  * @apiSuccess {Object} data An empty Object
  */

website/server/controllers/api-v3/groups.js

@@ -21,6 +21,21 @@ import { encrypt } from '../../libs/encryption';
 import { sendNotification as sendPushNotification } from '../../libs/pushNotifications';
 import pusher from '../../libs/pusher';
 
+/**
+ * @apiDefine GroupNotFound
+ * @apiError (404) {NotFound} GroupNotFound The specified group could not be found.
+ */
+
+/**
+ * @apiDefine PartyNotFound
+ * @apiError (404) {NotFound} PartyNotFound The user's party could not be found.
+ */
+
+/**
+ * @apiDefine GroupLeader Group Leader
+ * The group leader can use this route.
+ */
+
 let api = {};
 
 /**
@@ -123,6 +138,8 @@ api.getGroups = {
  * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
  *
  * @apiSuccess {Object} data The group object
+ *
+ * @apiUse GroupNotFound
  */
 api.getGroup = {
   method: 'GET',
@@ -160,6 +177,10 @@ api.getGroup = {
  * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
  *
  * @apiSuccess {Object} data The updated group
+ *
+ * @apiUse GroupNotFound
+ *
+ * @apiPermission GroupLeader
  */
 api.updateGroup = {
   method: 'PUT',
@@ -203,6 +224,8 @@ api.updateGroup = {
  * @apiParam {UUID} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
  *
  * @apiSuccess {Object} data The joined group
+ *
+ * @apiUse GroupNotFound
  */
 api.joinGroup = {
   method: 'POST',
@@ -361,6 +384,8 @@ api.rejectGroupInvite = {
  * @apiParam {String="remove-all","keep-all"} keep Query parameter - Whether to keep or not challenges' tasks. Defaults to keep-all
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse GroupNotFound
  */
 api.leaveGroup = {
   method: 'POST',
@@ -420,6 +445,10 @@ function _sendMessageToRemoved (group, removedUser, message) {
  * @apiParam {String} message Query parameter - The message to send to the removed members
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiPermission GroupLeader
+ *
+ * @apiUse GroupNotFound
  */
 api.removeGroupMember = {
   method: 'POST',
@@ -669,7 +698,7 @@ async function _inviteByEmail (invite, group, inviter, req, res) {
  *     ]
  *   }
  *
- * @apiError GroupNotFound The group could not be found
+ * @apiUse GroupNotFound
  * @apiError InvalidInvitationParams An error relating to the data sent in `emails` and/or `uuids`
  * @apiError TooManyInvites A max of 100 invites (combined emails and user ids) can be sent out at a time
  */

website/server/controllers/api-v3/hall.js

@@ -6,6 +6,11 @@ import {
 } from '../../libs/errors';
 import _ from 'lodash';
 
+/**
+ * @apiDefine Admin Moderators
+ * Contributors of tier 8 or higher can use this route.
+ */
+
 let api = {};
 
 /**
@@ -78,11 +83,14 @@ const heroAdminFields = 'contributor balance profile.name purchased items auth f
 
 /**
  * @api {get} /api/v3/hall/heroes/:heroId Get any user ("hero") given the UUID
- * @apiDescription Must be an admin to make this request.
  * @apiName GetHero
  * @apiGroup Hall
  *
  * @apiSuccess {Object} data The user object
+ *
+ * @apiPermission Admin
+ *
+ * @apiUse UserNotFound
  */
 api.getHero = {
   method: 'GET',
@@ -120,6 +128,10 @@ const gemsPerTier = {1: 3, 2: 3, 3: 3, 4: 4, 5: 4, 6: 4, 7: 4, 8: 0, 9: 0};
  * @apiGroup Hall
  *
  * @apiSuccess {Object} data The updated user object
+ *
+ * @apiPermission Admin
+ *
+ * @apiUse UserNotFound
  */
 api.updateHero = {
   method: 'PUT',

website/server/controllers/api-v3/members.js

@@ -28,6 +28,8 @@ let api = {};
  * @apiParam {UUID} memberId The member's id
  *
  * @apiSuccess {Object} data The member object
+ *
+ * @apiUse UserNotFound
  */
 api.getMember = {
   method: 'GET',
@@ -163,6 +165,8 @@ function _getMembersForItem (type) {
  * @apiParam {boolean} includeAllPublicFields Query parameter available only when fetching a party. If === `true` then all public fields for members will be returned (like when making a request for a single member)
  *
  * @apiSuccess {array} data An array of members, sorted by _id
+ * @apiUse ChallengeNotFound
+ * @apiUse GroupNotFound
  */
 api.getMembersForGroup = {
   method: 'GET',
@@ -181,6 +185,9 @@ api.getMembersForGroup = {
  * @apiParam {UUID} lastId Query parameter to specify the last invite returned in a previous request to this route and get the next batch of results
  *
  * @apiSuccess {array} data An array of invites, sorted by _id
+ *
+ * @apiUse ChallengeNotFound
+ * @apiUse GroupNotFound
  */
 api.getInvitesForGroup = {
   method: 'GET',
@@ -204,6 +211,9 @@ api.getInvitesForGroup = {
  * @apiParam {String} includeAllMembers BETA Query parameter - If 'true' all challenge members are returned
 
  * @apiSuccess {array} data An array of members, sorted by _id
+ *
+ * @apiUse ChallengeNotFound
+ * @apiUse GroupNotFound
  */
 api.getMembersForChallenge = {
   method: 'GET',
@@ -221,6 +231,9 @@ api.getMembersForChallenge = {
  * @apiParam {UUID} member The member _id
  *
  * @apiSuccess {Object} data Return an object with member _id, profile.name and a tasks object with the challenge tasks for the member
+ *
+ * @apiUse ChallengeNotFound
+ * @apiUse UserNotFound
  */
 api.getChallengeMemberProgress = {
   method: 'GET',
@@ -273,6 +286,8 @@ api.getChallengeMemberProgress = {
  * @apiParam {UUID} toUserId Body parameter - The user to contact
  *
  * @apiSuccess {Object} data An empty Object
+ *
+ * @apiUse UserNotFound
  */
 api.sendPrivateMessage = {
   method: 'POST',
@@ -334,6 +349,8 @@ api.sendPrivateMessage = {
  * @apiParam {Integer} gemAmount Body parameter The number of gems to send
  *
  * @apiSuccess {Object} data An empty Object
+ *
+ * @apiUse UserNotFound
  */
 api.transferGems = {
   method: 'POST',

website/server/controllers/api-v3/quests.js

@@ -26,17 +26,30 @@ function canStartQuestAutomatically (group)  {
   return _.every(group.quest.members, _.isBoolean);
 }
 
+/**
+ * @apiDefine QuestNotFound
+ * @apiError (404) {NotFound} QuestNotFound The specified quest could not be found.
+ */
+
+/**
+ * @apiDefine QuestLeader Quest Leader
+ * The quest leader can use this route.
+ */
+
 let api = {};
 
 /**
  * @api {post} /api/v3/groups/:groupId/quests/invite Invite users to a quest
  * @apiName InviteToQuest
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  * @apiParam {String} questKey
  *
  * @apiSuccess {Object} data Quest object
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.inviteToQuest = {
   method: 'POST',
@@ -142,11 +155,14 @@ api.inviteToQuest = {
 /**
  * @api {post} /api/v3/groups/:groupId/quests/accept Accept a pending quest
  * @apiName AcceptQuest
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.acceptQuest = {
   method: 'POST',
@@ -198,11 +214,14 @@ api.acceptQuest = {
 /**
  * @api {post} /api/v3/groups/:groupId/quests/reject Reject a quest
  * @apiName RejectQuest
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.rejectQuest = {
   method: 'POST',
@@ -255,11 +274,17 @@ api.rejectQuest = {
 /**
  * @api {post} /api/v3/groups/:groupId/quests/force-start Force-start a pending quest
  * @apiName ForceQuestStart
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
+ *
+ * @apiPermission QuestLeader
+ * @apiPermission GroupLeader
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.forceStart = {
   method: 'POST',
@@ -307,11 +332,17 @@ api.forceStart = {
 /**
  * @api {post} /api/v3/groups/:groupId/quests/cancel Cancel a quest that is not active
  * @apiName CancelQuest
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
+ *
+ * @apiPermission QuestLeader
+ * @apiPermission GroupLeader
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.cancelQuest = {
   method: 'POST',
@@ -355,11 +386,17 @@ api.cancelQuest = {
 /**
  * @api {post} /api/v3/groups/:groupId/quests/abort Abort the current quest
  * @apiName AbortQuest
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
+ *
+ * @apiPermission QuestLeader
+ * @apiPermission GroupLeader
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.abortQuest = {
   method: 'POST',
@@ -407,11 +444,14 @@ api.abortQuest = {
 /**
  * @api {post} /api/v3/groups/:groupId/quests/leave Leave the active quest
  * @apiName LeaveQuest
- * @apiGroup Group
+ * @apiGroup Quest
  *
  * @apiParam {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
+ *
+ * @apiUse GroupNotFound
+ * @apiUse QuestNotFound
  */
 api.leaveQuest = {
   method: 'POST',

website/server/controllers/api-v3/tags.js

@@ -7,6 +7,11 @@ import {
 import _ from 'lodash';
 import { removeFromArray } from '../../libs/collectionManipulators';
 
+/**
+ * @apiDefine TagNotFound
+ * @apiError (404) {NotFound} TagNotFound The specified tag could not be found.
+ */
+
 let api = {};
 
 /**
@@ -57,6 +62,8 @@ api.getTags = {
  * @apiParam {UUID} tagId The tag _id
  *
  * @apiSuccess {Object} data The tag object
+ *
+ * @apiUse TagNotFound
  */
 api.getTag = {
   method: 'GET',
@@ -84,6 +91,8 @@ api.getTag = {
  * @apiParam {UUID} tagId The tag _id
  *
  * @apiSuccess {Object} data The updated tag
+ *
+ * @apiUse TagNotFound
  */
 api.updateTag = {
   method: 'PUT',
@@ -118,6 +127,8 @@ api.updateTag = {
  * @apiParam {Number} to Position the tag is moving to
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse TagNotFound
  */
 api.reorderTags = {
   method: 'POST',
@@ -151,6 +162,8 @@ api.reorderTags = {
  * @apiParam {UUID} tagId The tag _id
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse TagNotFound
  */
 api.deleteTag = {
   method: 'DELETE',

website/server/controllers/api-v3/tasks.js

@@ -21,6 +21,16 @@ import Bluebird from 'bluebird';
 import _ from 'lodash';
 import logger from '../../libs/logger';
 
+/**
+ * @apiDefine TaskNotFound
+ * @apiError (404) {NotFound} TaskNotFound The specified task could not be found.
+ */
+
+/**
+ * @apiDefine ChecklistNotFound
+ * @apiError (404) {NotFound} ChecklistNotFound The specified checklist item could not be found.
+ */
+
 let api = {};
 let requiredGroupFields = '_id leader tasksOrder name';
 
@@ -60,6 +70,8 @@ api.createUserTasks = {
  * @apiParam {UUID} challengeId The id of the challenge the new task(s) will belong to
  *
  * @apiSuccess data An object if a single task was created, otherwise an array of tasks
+ *
+ * @apiUse ChallengeNotFound
  */
 api.createChallengeTasks = {
   method: 'POST',
@@ -126,6 +138,8 @@ api.getUserTasks = {
  * @apiParam {string="habits","dailys","todos","rewards"} type Optional query parameter to return just a type of tasks
  *
  * @apiSuccess {Array} data An array of tasks
+ *
+ * @apiUse ChallengeNotFound
  */
 api.getChallengeTasks = {
   method: 'GET',
@@ -160,6 +174,8 @@ api.getChallengeTasks = {
  * @apiParam {String} taskId The task _id or alias
  *
  * @apiSuccess {Object} data The task object
+ *
+ * @apiUse TaskNotFound
  */
 api.getTask = {
   method: 'GET',
@@ -193,6 +209,9 @@ api.getTask = {
  * @apiParam {String} taskId The task _id or alias
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
+ * @apiUse ChallengeNotFound
  */
 api.updateTask = {
   method: 'PUT',
@@ -275,6 +294,8 @@ api.updateTask = {
  * @apiSuccess {Object} data._tmp If an item was dropped it'll be returned in te _tmp object
  * @apiSuccess {Number} data.delta The delta
  * @apiSuccess {Object} data The user stats
+ *
+ * @apiUse TaskNotFound
  */
 api.scoreTask = {
   method: 'POST',
@@ -369,6 +390,8 @@ api.scoreTask = {
  * @apiParam {Number} position Query parameter - Where to move the task (-1 means push to bottom). First position is 0
  *
  * @apiSuccess {Array} data The new tasks order (user.tasksOrder.{task.type}s)
+ *
+ * @apiUse TaskNotFound
  */
 api.moveTask = {
   method: 'POST',
@@ -420,6 +443,9 @@ api.moveTask = {
  * @apiParam {String} taskId The task _id or alias
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
+ * @apiUse ChallengeNotFound
  */
 api.addChecklistItem = {
   method: 'POST',
@@ -474,6 +500,9 @@ api.addChecklistItem = {
  * @apiParam {UUID} itemId The checklist item _id
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
+ * @apiUse ChecklistNotFound
  */
 api.scoreCheckListItem = {
   method: 'POST',
@@ -513,6 +542,10 @@ api.scoreCheckListItem = {
  * @apiParam {UUID} itemId The checklist item _id
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
+ * @apiUse ChecklistNotFound
+ * @apiUse ChallengeNotFound
  */
 api.updateChecklistItem = {
   method: 'PUT',
@@ -570,6 +603,10 @@ api.updateChecklistItem = {
  * @apiParam {UUID} itemId The checklist item _id
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
+ * @apiUse ChallengeNotFound
+ * @apiUse ChecklistNotFound
  */
 api.removeChecklistItem = {
   method: 'DELETE',
@@ -625,6 +662,8 @@ api.removeChecklistItem = {
  * @apiParam {UUID} tagId The tag id
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
  */
 api.addTagToTask = {
   method: 'POST',
@@ -665,6 +704,9 @@ api.addTagToTask = {
  * @apiParam {UUID} tagId The tag id
  *
  * @apiSuccess {Object} data The updated task
+ *
+ * @apiUse TaskNotFound
+ * @apiUse TagNotFound
  */
 api.removeTagFromTask = {
   method: 'DELETE',
@@ -762,6 +804,8 @@ api.unlinkAllTasks = {
  * @apiParam {String} keep Query parameter - keep or remove
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse TaskNotFound
  */
 api.unlinkOneTask = {
   method: 'POST',
@@ -838,6 +882,9 @@ api.clearCompletedTodos = {
  * @apiParam {String} taskId The task _id or alias
  *
  * @apiSuccess {Object} data An empty object
+ *
+ * @apiUse TaskNotFound
+ * @apiUse ChallengeNotFound
  */
 api.deleteTask = {
   method: 'DELETE',

website/server/controllers/api-v3/user.js

@@ -15,6 +15,11 @@ import Bluebird from 'bluebird';
 import _ from 'lodash';
 import * as passwordUtils from '../../libs/password';
 
+/**
+ * @apiDefine UserNotFound
+ * @apiError (404) {NotFound} UserNotFound The specified user could not be found.
+ */
+
 let api = {};
 
 /**
@@ -328,6 +333,10 @@ const partyMembersFields = 'profile.name stats achievements items.special';
  * brightness: "Searing Brightness"
  * healAll: "Blessing"
  *
+ * @apiUse TaskNotFound
+ * @apiUse PartyNotFound
+ * @apiUse UserNotFound
+ *
  */
 api.castSpell = {
   method: 'POST',
@@ -1069,7 +1078,7 @@ api.userRebirth = {
  * @apiParam {UUID} uuid The uuid of the user to block / unblock
  *
  * @apiSuccess {Array} data user.inbox.blocks
-**/
+ */
 api.blockUser = {
   method: 'POST',
   middlewares: [authWithHeaders()],
@@ -1090,7 +1099,7 @@ api.blockUser = {
  * @apiParam {UUID} id The id of the message to delete
  *
  * @apiSuccess {Object} data user.inbox.messages
-**/
+ */
 api.deleteMessage = {
   method: 'DELETE',
   middlewares: [authWithHeaders()],
@@ -1109,7 +1118,7 @@ api.deleteMessage = {
  * @apiGroup User
  *
  * @apiSuccess {Object} data user.inbox.messages
-**/
+ */
 api.clearMessages = {
   method: 'DELETE',
   middlewares: [authWithHeaders()],
@@ -1128,7 +1137,7 @@ api.clearMessages = {
  * @apiGroup User
  *
  * @apiSuccess {Object} data user.inbox.messages
-**/
+ */
 api.markPmsRead = {
   method: 'POST',
   middlewares: [authWithHeaders()],

website/server/controllers/api-v3/webhook.js

@@ -14,7 +14,7 @@ let api = {};
 
 /**
  * @apiDefine WebhookNotFound
- * @apiError (404) {NotFound} WebhookNotFound The specified Webhook could not be found.
+ * @apiError (404) {NotFound} WebhookNotFound The specified webhook could not be found.
  */
 
 /**

website/server/controllers/top-level/dataexport.js

@@ -146,6 +146,8 @@ api.exportUserDataXml = {
  * @apiDescription NOTE: Part of the private API that may change at any time.
  *
  * @apiSuccess {String} An html page
+ *
+ * @apiUse UserNotFound
  */
 api.exportUserAvatarHtml = {
   method: 'GET',

website/server/controllers/top-level/email.js

@@ -17,6 +17,8 @@ let api = {};
  * @apiParam {String} code Query parameter - An unsubscription code
  *
  * @apiSuccess {String} An html success message
+ *
+ * @apiUse UserNotFound
  */
 api.unsubscribe = {
   method: 'GET',