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

make corrections and improvements to apidocs (no code changes)

Browse Source
This commit is contained in:
Alys
2020-02-08 14:12:20 +10:00
parent 71cc313c9a
commit c5d0ff63a5
16 changed files with 116 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
website/server/controllers/api-v3/auth.js
View File

@@ -29,7 +29,7 @@ const api = {};
/**
* @api {post} /api/v3/user/auth/local/register Register
* @apiDescription Register a new user with email, login name, and password or
* attach local auth to a social user
* attach local authentication to a social-auth user
* @apiName UserRegisterLocal
* @apiGroup User
*
@@ -148,12 +148,14 @@ api.loginSocial = {
/**
* @api {put} /api/v3/user/auth/update-username Update username
* @apiDescription Update the username of a local user
* @apiDescription Update and verify the user's username
* @apiName UpdateUsername
* @apiGroup User
*
* @apiParam (Body) {String} username The new username
* @apiParam (Body) {String} password The user's password if they use local authentication.
* Omit if they use social auth.
*
* @apiSuccess {String} data.username The new username
* */
api.updateUsername = {
@@ -196,6 +198,8 @@ api.updateUsername = {
// save username
user.auth.local.lowerCaseUsername = newUsername.toLowerCase();
user.auth.local.username = newUsername;
// reward user for verifying their username
if (!user.flags.verifiedUsername) {
user.flags.verifiedUsername = true;
if (user.items.pets['Bear-Veteran']) {
@@ -277,7 +281,7 @@ api.updatePassword = {
};
/**
* @api {post} /api/v3/user/reset-password Reset password
* @api {post} /api/v3/user/reset-password Reset password (email a reset link)
* @apiDescription Send the user an email to let them reset their password
* @apiName ResetPassword
* @apiGroup User
@@ -371,7 +375,7 @@ api.updateEmail = {
};
/**
* @api {post} /api/v3/user/auth/reset-password-set-new-one Reset Password Set New one
* @api {post} /api/v3/user/auth/reset-password-set-new-one Reset password (set a new one)
* @apiDescription Set a new password for a user that reset theirs. Not meant for public usage.
* @apiName ResetPasswordSetNewOne
* @apiGroup User
@@ -424,8 +428,8 @@ api.resetPasswordSetNewOne = {
/**
* @api {delete} /api/v3/user/auth/social/:network Delete social authentication method
* @apiDescription Remove a social authentication method (only facebook supported)
* from a user profile. The user must have local authentication enabled
* @apiDescription Remove a social authentication method from a user profile.
* The user must have another authentication method enabled.
* @apiName UserDeleteSocial
* @apiGroup User
*

2
website/server/controllers/api-v3/challenges.js
View File

@@ -513,7 +513,7 @@ api.getGroupChallenges = {
};
/**
* @api {get} /api/v3/challenges/:challengeId Get a challenge given its id
* @api {get} /api/v3/challenges/:challengeId Get a challenge
* @apiName GetChallenge
* @apiGroup Challenge
*

3
website/server/controllers/api-v3/cron.js
View File

@@ -4,8 +4,9 @@ import cron from '../../middlewares/cron';
const api = {};
/**
* @api {post} /api/v3/cron Runs cron
* @api {post} /api/v3/cron Run cron
* @apiName Cron
* @apiDescription This causes cron to run. It assumes that the user has already been shown the Record Yesterday's Activity ("Check off any Dailies you did yesterday") screen and so it will immediately apply damage for incomplete due Dailies.
* @apiGroup Cron
*
* @apiSuccess {Object} data An empty Object

10
website/server/controllers/api-v3/hall.js
View File

@@ -93,7 +93,7 @@ api.getPatrons = {
};
/**
* @api {get} /api/v3/hall/heroes Get all Heroes
* @api {get} /api/v3/hall/heroes Get all Heroes (contributors)
* @apiName GetHeroes
* @apiGroup Hall
*
@@ -154,7 +154,7 @@ const heroAdminFields = 'contributor balance profile.name purchased items auth f
* @apiGroup Hall
* @apiPermission Admin
*
* @apiDescription Returns the profile of the given user
* @apiDescription Returns the profile of the given user. The user does not need to be a contributor.
*
* @apiSuccess {Object} data The user object
*
@@ -208,9 +208,9 @@ const gemsPerTier = {
* @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.
* @apiDescription Update user's gem balance, contributions and contribution tier,
* or admin status. Grant items. Block / unblock user's account.
* Revoke / unrevoke chat privileges.
*
* @apiExample Example Body:
* {

6
website/server/controllers/api-v3/members.js
View File

@@ -658,8 +658,8 @@ api.getObjectionsToInteraction = {
* @apiName SendPrivateMessage
* @apiGroup Member
*
* @apiParam (Body) {String} message Body parameter - The message
* @apiParam (Body) {UUID} toUserId Body parameter - The user to contact
* @apiParam (Body) {String} message The message
* @apiParam (Body) {UUID} toUserId The user to contact
*
* @apiSuccess {Object} data.message The message just sent
*
@@ -698,7 +698,7 @@ api.sendPrivateMessage = {
* @apiGroup Member
*
* @apiParam (Body) {String} message The message to the user
* @apiParam (Body) {UUID} toUserId The toUser _id
* @apiParam (Body) {UUID} toUserId The user to send the gift to
* @apiParam (Body) {Integer} gemAmount The number of gems to send
*
* @apiSuccess {Object} data An empty Object

4
website/server/controllers/api-v3/news.js
View File

@@ -53,8 +53,10 @@ api.getNews = {
};
/**
* @api {post} /api/v3/news/tell-me-later Get latest Bailey announcement in a second moment
* @api {post} /api/v3/news/tell-me-later Allow latest Bailey announcement to be read later
* @apiName TellMeLaterNews
* @apiDescription Add a notification to allow viewing of the latest "New Stuff by Bailey" message.
* Prevent this specific Bailey message from appearing automatically.
* @apiGroup News
*
*

4
website/server/controllers/api-v3/tags.js
View File

@@ -78,7 +78,7 @@ api.getTags = {
};
/**
* @api {get} /api/v3/tags/:tagId Get a tag given its id
* @api {get} /api/v3/tags/:tagId Get a tag
* @apiName GetTag
* @apiGroup Tag
*
@@ -199,7 +199,7 @@ api.reorderTags = {
};
/**
* @api {delete} /api/v3/tags/:tagId Delete a user tag given its id
* @api {delete} /api/v3/tags/:tagId Delete a user tag
* @apiName DeleteTag
* @apiGroup Tag
*

5
website/server/controllers/api-v3/tasks.js
View File

@@ -1477,8 +1477,9 @@ api.unlinkOneTask = {
};
/**
* @api {post} /api/v3/tasks/clearCompletedTodos Delete user's completed todos
* @api {post} /api/v3/tasks/clearCompletedTodos Delete user's completed To-Dos
* @apiName ClearCompletedTodos
* @apiDescription Deletes all of a user's completed To-Dos except those belonging to active Challenges and Group Plans
* @apiGroup Task
*
* @apiExample {curl} Example call:
@@ -1523,7 +1524,7 @@ api.clearCompletedTodos = {
};
/**
* @api {delete} /api/v3/tasks/:taskId Delete a task given its id
* @api {delete} /api/v3/tasks/:taskId Delete a task
* @apiName DeleteTask
* @apiGroup Task
*

15
website/server/controllers/api-v3/tasks/groups.js
View File

@@ -112,8 +112,7 @@ api.getGroupTasks = {
};
/**
* @api {post} /api/v3/group/:groupId/tasks/:taskId/move/to/:position Move a group task to
* a specified position
* @api {post} /api/v3/group/:groupId/tasks/:taskId/move/to/:position Move a group task to a specified position
* @apiDescription Moves a group task to a specified position
* @apiVersion 3.0.0
* @apiName GroupMoveTask
@@ -178,7 +177,7 @@ api.groupMoveTask = {
* @apiParam (Path) {UUID} taskId The id of the task that will be assigned
* @apiParam (Path) {UUID} assignedUserId The id of the user that will be assigned to the task
*
* @apiSuccess data An object if a single task was created, otherwise an array of tasks
* @apiSuccess data The assigned task
*/
api.assignTask = {
method: 'POST',
@@ -246,14 +245,14 @@ api.assignTask = {
/**
* @api {post} /api/v3/tasks/:taskId/unassign/:assignedUserId Unassign a user from a task
* @apiDescription Unassigns a user to from a group task
* @apiDescription Unassigns a user from a group task
* @apiName UnassignTask
* @apiGroup Task
*
* @apiParam (Path) {UUID} taskId The id of the task that will be assigned
* @apiParam (Path) {UUID} taskId The id of the task that is the original group task
* @apiParam (Path) {UUID} assignedUserId The id of the user that will be unassigned from the task
*
* @apiSuccess data An object if a single task was created, otherwise an array of tasks
* @apiSuccess data The unassigned task
*/
api.unassignTask = {
method: 'POST',
@@ -398,8 +397,8 @@ api.approveTask = {
};
/**
* @api {post} /api/v3/tasks/:taskId/needs-work/:userId Group task needs more work
* @apiDescription Mark an assigned group task as needeing more work before it can be approved
* @api {post} /api/v3/tasks/:taskId/needs-work/:userId Require more work for a group task
* @apiDescription Mark an assigned group task as needing more work before it can be approved
* @apiVersion 3.0.0
* @apiName TaskNeedsWork
* @apiGroup Task

95
website/server/controllers/api-v3/user.js
View File

@@ -41,28 +41,28 @@ const api = {};
* @apiGroup User
*
* @apiDescription The user profile contains data related to the authenticated
* user including (but not limited to);
* Achievements
* Authentications (including types and timestamps)
* Challenges
* Flags (including armoire, tutorial, tour etc...)
* Guilds
* History (including timestamps and values)
* Inbox
* Invitations (to parties/guilds)
* Items (character's full inventory)
* New Messages (flags for groups/guilds that have new messages)
* Notifications
* Party (includes current quest information)
* Preferences (user selected prefs)
* Profile (name, photo url, blurb)
* Purchased (includes purchase history, gem purchased items, plans)
* PushDevices (identifiers for mobile devices authorized)
* Stats (standard RPG stats, class, buffs, xp, etc..)
* Tags
* TasksOrder (list of all ids for dailys, habits, rewards and todos)
* user including (but not limited to):
* Achievements;
* Authentications (including types and timestamps);
* Challenges memberships (Challenge IDs);
* Flags (including armoire, tutorial, tour etc...);
* Guilds memberships (Guild IDs);
* History (including timestamps and values, only for Experience and summed To-Do values);
* Inbox;
* Invitations (to parties/guilds);
* Items (character's full inventory);
* New Messages (flags for party/guilds that have new messages; also reported in Notifications);
* Notifications;
* Party (includes current quest information);
* Preferences (user selected prefs);
* Profile (name, photo url, blurb);
* Purchased (includes subscription data and some gem-purchased items);
* PushDevices (identifiers for mobile devices authorized);
* Stats (standard RPG stats, class, buffs, xp, etc..);
* Tags;
* TasksOrder (list of all IDs for Dailys, Habits, Rewards and To-Dos).
*
* @apiParam (Query) {String} [userFields] A list of comma separated user fields to
* @apiParam (Query) {String} [userFields] A list of comma-separated user fields to
* be returned instead of the entire document.
* Notifications are always returned.
*
@@ -91,8 +91,7 @@ api.getUser = {
};
/**
* @api {get} /api/v3/user/inventory/buy Get the gear items available for purchase
* for the authenticated user
* @api {get} /api/v3/user/inventory/buy Get the gear items available for purchase for the authenticated user
* @apiName UserGetBuyList
* @apiGroup User
*
@@ -231,7 +230,7 @@ api.updateUser = {
* @apiName UserDelete
* @apiGroup User
*
* @apiParam (Body) {String} password The user's password if the account uses local authentication
* @apiParam (Body) {String} password The user's password if the account uses local authentication, otherwise the localized word "DELETE"
* @apiParam (Body) {String} feedback User's optional feedback explaining reasons for deletion
*
* @apiSuccess {Object} data An empty Object
@@ -242,9 +241,11 @@ api.updateUser = {
* "data": {}
* }
*
* @apiError {BadRequest} MissingPassword The password was not included in the request
* @apiError {BadRequest} LengthExceeded The feedback provided is longer than 10K
* @apiError {BadRequest} NotAuthorized There is no account that uses those credentials.
* @apiError {BadRequest} MissingPassword Missing password.
* @apiError {BadRequest} NotAuthorized Wrong password.
* @apiError {BadRequest} NotAuthorized Please type DELETE in all capital letters to delete your account.
* @apiError {BadRequest} BadRequest Account deletion feedback is limited to 10,000 characters. For lengthy feedback, email ${TECH_ASSISTANCE_EMAIL}.
* @apiError {BadRequest} NotAuthorized You have an active subscription, cancel your plan before deleting your account.
*
* @apiErrorExample {json}
* {
@@ -279,7 +280,7 @@ api.deleteUser = {
}
const { feedback } = req.body;
if (feedback && feedback.length > 10000) throw new BadRequest(`Account deletion feedback is limited to 10,000 characters. For lengthy feedback, email ${TECH_ASSISTANCE_EMAIL}.`);
if (feedback && feedback.length > 10000) throw new BadRequest(`Account deletion feedback is limited to 10,000 characters. For lengthy feedback, email ${TECH_ASSISTANCE_EMAIL}.`); // @TODO localize this string
if (plan && plan.customerId && !plan.dateTerminated) {
throw new NotAuthorized(res.t('cannotDeleteActiveAccount'));
@@ -333,14 +334,14 @@ function _cleanChecklist (task) {
* @apiGroup User
*
* @apiDescription Returns the user's data without:
* Authentication information
* NewMessages/Invitations/Inbox
* Profile
* Purchased information
* Contributor information
* Special items
* Webhooks
* Notifications
* Authentication information,
* NewMessages/Invitations/Inbox,
* Profile,
* Purchased information,
* Contributor information,
* Special items,
* Webhooks,
* Notifications.
*
* @apiSuccess {Object} data.user
* @apiSuccess {Object} data.tasks
@@ -537,7 +538,7 @@ api.buyGear = {
};
/**
* @api {post} /api/v3/user/buy-armoire Buy an armoire item
* @api {post} /api/v3/user/buy-armoire Buy an Enchanted Armoire item
* @apiName UserBuyArmoire
* @apiGroup User
*
@@ -619,8 +620,9 @@ api.buyHealthPotion = {
};
/**
* @api {post} /api/v3/user/buy-mystery-set/:key Buy a mystery set
* @api {post} /api/v3/user/buy-mystery-set/:key Buy a Mystery Item set
* @apiName UserBuyMysterySet
* @apiDescription This buys a Mystery Item set using an Hourglass.
* @apiGroup User
*
* @apiParam (Path) {String} key The mystery set to buy
@@ -703,7 +705,7 @@ api.buyQuest = {
};
/**
* @api {post} /api/v3/user/buy-special-spell/:key Buy special "spell" item
* @api {post} /api/v3/user/buy-special-spell/:key Buy special item (card, avatar transformation, etc)
* @apiDescription Includes gift cards (e.g., birthday card), and avatar Transformation
* Items and their antidotes (e.g., Snowball item and Salt reward).
* @apiName UserBuySpecialSpell
@@ -1003,6 +1005,8 @@ api.purchase = {
/**
* @api {post} /api/v3/user/purchase-hourglass/:type/:key Purchase Hourglass-purchasable item
* @apiName UserPurchaseHourglass
* @apiDescription Purchases an Hourglass-purchasable item.
* Does not include Mystery Item sets (use /api/v3/user/buy-mystery-set/:key).
* @apiGroup User
*
* @apiParam (Path) {String="pets","mounts"} type The type of item to purchase
@@ -1492,7 +1496,7 @@ api.clearMessages = {
};
/**
* @api {post} /api/v3/user/mark-pms-read Marks Private Messages as read
* @api {post} /api/v3/user/mark-pms-read Mark Private Messages as read
* @apiName markPmsRead
* @apiGroup User
*
@@ -1517,7 +1521,7 @@ api.markPmsRead = {
/* NOTE this route has also an API v4 version */
/**
* @api {post} /api/v3/user/reroll Reroll a user using the Fortify Potion
* @api {post} /api/v3/user/reroll Reroll a user (reset tasks) using the Fortify Potion
* @apiName UserReroll
* @apiGroup User
*
@@ -1580,14 +1584,12 @@ api.userReset = {
};
/**
* @api {post} /api/v3/user/custom-day-start Set preferences.dayStart
* (Custom Day Start time) for user.
* @api {post} /api/v3/user/custom-day-start Set Custom Day Start time for user.
* @apiName setCustomDayStart
* @apiGroup User
*
*
* @apiParam (Body) {number} [dayStart=0] The hour number 0-23 for day to begin.
* If body is not included, will default to 0.
* If not supplied, will default to 0.
*
* @apiParamExample {json} Request-Example:
* {"dayStart":2}
@@ -1666,8 +1668,7 @@ api.togglePinnedItem = {
};
/**
* @api {post} /api/v3/user/move-pinned-item/:type/:path/move/to/:position Move a pinned
* item in the rewards column to a new position after being sorted
* @api {post} /api/v3/user/move-pinned-item/:type/:path/move/to/:position Move a pinned item in the rewards column to a new position after being sorted
* @apiName MovePinnedItem
* @apiGroup User
*

41
website/server/controllers/api-v3/user/spells.js
View File

@@ -30,29 +30,30 @@ const api = {};
* the necessary fields will be populated. The user is always returned.
*
* @apiDescription Skill Key to Name Mapping
* Mage
* fireball: "Burst of Flames"
* mpheal: "Ethereal Surge"
* earth: "Earthquake"
* frost: "Chilling Frost"
*
* Warrior
* smash: "Brutal Smash"
* defensiveStance: "Defensive Stance"
* valorousPresence: "Valorous Presence"
* intimidate: "Intimidating Gaze"
* Mage:
* fireball="Burst of Flames",
* mpheal="Ethereal Surge",
* earth="Earthquake",
* frost="Chilling Frost"
*
* Rogue
* pickPocket: "Pickpocket"
* backStab: "Backstab"
* toolsOfTrade: "Tools of the Trade"
* stealth: "Stealth"
* Warrior:
* smash="Brutal Smash",
* defensiveStance="Defensive Stance",
* valorousPresence="Valorous Presence",
* intimidate="Intimidating Gaze"
*
* Healer
* heal: "Healing Light"
* protectAura: "Protective Aura"
* brightness: "Searing Brightness"
* healAll: "Blessing"
* Rogue:
* pickPocket="Pickpocket",
* backStab="Backstab",
* toolsOfTrade="Tools of the Trade",
* stealth="Stealth"
*
* Healer:
* heal="Healing Light",
* protectAura="Protective Aura",
* brightness="Searing Brightness",
* healAll="Blessing"
*
* @apiError (400) {NotAuthorized} Not enough mana.
* @apiUse TaskNotFound

3
website/server/controllers/api-v3/user/stats.js
View File

@@ -5,8 +5,7 @@ import { authWithHeaders } from '../../../middlewares/auth';
const api = {};
/**
* @api {post} /api/v3/user/allocate Allocate a single Stat Point
* (previously called Attribute Point)
* @api {post} /api/v3/user/allocate Allocate a single Stat Point (previously called Attribute Point)
* @apiName UserAllocate
* @apiGroup User
*

2
website/server/controllers/api-v4/inbox.js
View File

@@ -77,7 +77,7 @@ api.clearMessages = {
* @api {get} /api/v4/inbox/conversations Get the conversations for a user
* @apiName conversations
* @apiGroup Inbox
* @apiDescription Get the conversations for a user
* @apiDescription Get the conversations for a user. This is for API v4 which must not be used in third-party tools. Use "Get inbox messages for a user" instead.
*
* @apiSuccess {Array} data An array of inbox conversations
*

4
website/server/controllers/api-v4/members.js
View File

@@ -5,8 +5,8 @@ const api = {};
/**
* @api {post} /api/v4/members/flag-private-message/:messageId Flag a private message
* @apiDescription An email and slack message are sent
* to the moderators about every flagged message.
* @apiDescription Moderators are notified about every flagged message, including the sender, recipient, and full content of the message.
* This route is for API v4 which must not be used in third-party tools as it can change without notice. There is no equivalent route in API v3.
* @apiName FlagPrivateMessage
* @apiGroup Member
*

3
website/server/controllers/top-level/dataexport.js
View File

@@ -161,6 +161,7 @@ api.exportUserDataJson = {
/**
* @api {get} /export/userdata.xml Export user data in XML format
* @apiName ExportUserDataXml
* @apiDescription This XML export feature is not currently working. Refer to https://github.com/HabitRPG/habitica/issues/10100 for details.
* @apiGroup DataExport
*
* @apiSuccess {XML} File An xml file of the user object.
@@ -224,6 +225,7 @@ api.exportUserAvatarHtml = {
/**
* @api {get} /export/avatar-:uuid.png Render a user avatar as a PNG file
* @apiName ExportUserAvatarPng
* @apiDescription This PNG export feature is not currently working. Refer to https://github.com/HabitRPG/habitica/issues/9489 for details.
* @apiGroup DataExport
*
* @apiParam (Path) {String} uuid The User ID of the user
@@ -293,6 +295,7 @@ api.exportUserAvatarPng = {
/**
* @api {get} /export/inbox.html Export user private messages as HTML document
* @apiName ExportUserPrivateMessages
* @apiDescription This HTML export feature is not currently working. Refer to https://github.com/HabitRPG/habitica/issues/9489 for details.
* @apiGroup DataExport
*
* @apiSuccess {HTML} File An html page of the user's private messages.

6
website/server/controllers/top-level/email.js
View File

@@ -8,14 +8,14 @@ import {
const api = {};
/**
* @api {get} /email/unsubscribe Unsubscribe an email or user from email notifications
* @apiDescription Does not require authentication
* @api {get} /email/unsubscribe Unsubscribe an email address or user from email notifications
* @apiName UnsubscribeEmail
* @apiGroup Unsubscribe
* @apiDescription This is a GET method included in official emails from Habitica
* that will unsubscribe the user from emails.
* Does not require authentication.
*
* @apiParam (Query) {String} code An unsubscription code
* @apiParam (Query) {String} code An unsubscription code that contains an encrypted User ID or email address
*
* @apiSuccess {String} Webpage An html success message
*